API Guide Home (Online version only) |

# NetMasterLibTypes.h

Go to the documentation of this file.

    00001 /******************************************************************************
    00002  * Copyright (c) 2004 palmOne, Inc. or its subsidiaries.
    00003  * All rights reserved.
    00004  *****************************************************************************/
    00005 /**
    00006  * @ingroup NETMASTER
    00007  */
    00008
    00009 /**
    00010  * @file    NetMasterLibTypes.h
    00011  * @version 1.0
    00012  * @date    01/31/2002
    00013  *
    00014  * @brief This file contains public data types exported by the NetMaster Library
    00015  *
    00016  * For usage model: @see NetMasterLibrary.h
    00017  */
    00018
    00019
    00020 #ifndef _NET_MASTER_LIB_TYPES_H_
    00021 #define _NET_MASTER_LIB_TYPES_H_
    00022
    00023
    00024
    00025 /** Opaque structures */
    00026 struct NetMasterContextTypeTag;
    00027
    00028
    00029 /**
    00030  * @name NetMaster API Version Number
    00031  * @brief Current library API version number returned by NetMasterLibVersionGet()
    00032  */
    00033 /*@{*/
    00034 #define netMasterLibVersionMajor      0
    00035 #define netMasterLibVersionMinor      4
    00036 #define netMasterLibVersionBugFix     0
    00037 /*@}*/
    00038
    00039 // Change details:
    00040 // 0.1.0 -- original
    00041 // 0.2.0: implemented original VPN override notification
    00042 // 0.3.0: implemented NetMasterNetLibOpenWithOptions ().
    00043 // 0.4.0: implemented initial Palm OS 5.x support, including
    00044 //         initial Data Session Control API.
    00045
    00046
    00047 /** TCP/IP Network Auto-login definitions used by NetMasterAutoLoginSettingGet()
    00048  *  and NetMasterAutoLoginSettingSet()
    00049  */
    00050 typedef UInt32  NetMasterAutoLoginType;
    00051 enum
    00052   {
    00053     /**
    00054      *  For CDMA 1xRTT: Automatically log in to the TCP/IP network when the
    00055      *  wireless mode is turned on and network is acquired;
    00056      *  For GSM GPRS: Attempt to attach when the radio is powered on (ideally
    00057      *  a combined attach)
    00058      */
    00059     // NOTE: Used by Handspring's Network Panel
    00060     netMasterAutoLoginWhenWirelessOn    = 0x00000001UL,
    00061
    00062     /**
    00063      * Prompt the user before connecting to the Internet;
    00064      * Also known as the "NetGuard" feature.
    00065      */
    00066     // NOTE: Used by Handspring's Network Panel
    00067     netMasterLoginNetGuardEnabled       = 0x00000002UL,
    00068
    00069     netMasterAutoLoginClearAll          = 0xFFFFFFFFUL
    00070   };
    00071
    00072
    00073 /** NetLib interface shutdown options for NetMasterNetInterfacesShutDown */
    00074 typedef UInt32  NetMasterNetIFShutDownOptionsType;
    00075 enum
    00076   {
    00077     /** If the Progress dialog is up, dismiss it even if it is
    00078      *  in the error display state
    00079      */
    00080     netMasterNetIFShutDownOptDismissPrgDialog   = 0x00000001UL,
    00081
    00082     /** If set, and the session being connected at the moment has
    00083      *  a fallback, this will allow the fallback to be processed (for example,
    00084      *  when aborting GPRS logon, but allowing the fallback, if any, to
    00085      *  take place)
    00086      */
    00087     netMasterNetIFShutDownOptCurrentOnly        = 0x00000002UL,
    00088
    00089
    00090     /** If set, will cause the cached NetGuard setting to be
    00091      *  cleared: apps that Disconnect the network connection as the
    00092      *  result of user request (such as Disconnect button or menu item),
    00093      *  MUST set this flag -- this causes the system to put up the
    00094      *  NetGuard prompt during a subsequent data network login,
    00095      *  if dictated by the netMasterLoginNetGuardEnabled setting.
    00096      *
    00097      *  If *not* set, will cause the cached NetGuard setting to
    00098      *  be preserved.
    00099      */
    00100     netMasterNetIFShutDownOptResetNetGuard      = 0x00000004UL
    00101
    00102
    00103   };
    00104
    00105
    00106 // ------------------------------------------------------------------
    00107 // Client Notification Events: (netMasterClientEventNotificationTypeID)
    00108 //
    00109 // Parameter block and supporting data structures sent to the currently
    00110 // registered NetMaster library client(s) via Palm OS Notification Manager.
    00111 // ------------------------------------------------------------------
    00112
    00113 /** The application that wishes to receive these notifications registers
    00114  *  via Palm OS Notification Manager's SysNotifyRegister() for the event type
    00115  *  netMasterClientEventNotificationTypeID to receive the events listed in
    00116  *  NetMasterClientEventEnum. See Palm OS Notification Manager
    00117  *  documentation for registration and notification handling details.
    00118  */
    00119 // (Handspring registered 'HICe' with Palm Source on 08-Oct-2002 at 8:23pm PST)
    00120 #define netMasterClientEventNotificationTypeID    'HnMe'
    00121
    00122
    00123 /** NetMaster library client event selector */
    00124 typedef UInt16    NetMasterClientEventEnum;
    00125 enum
    00126   {
    00127     netMasterClientEventUnknown     = 0,    // reserve 0
    00128
    00129     /** Queries the VPN vendor to install its own connection profile name,
    00130      *  if any; NetMaster library broadcasts this event to all registered
    00131      *  clients from the context of the UI task when a client application
    00132      *  calls NetLibOpen() or NetLibOpenConfig().
    00133      *  Parameter block:
    00134      *  NetMasterClientEventInfoType:NetMasterClientEventVPNConnInstallType
    00135      */
    00136     netMasterClientEventVPNConnInstall,
    00137
    00138
    00139
    00140
    00141     netMasterClientEventLAST
    00142   };
    00143
    00144
    00145
    00146 /**
    00147  * @brief Data block for netMasterClientEventVPNConnInstall
    00148  */
    00149 typedef struct
    00150   {
    00151     // --------------------------------------------------------------
    00152     // Inputs
    00153     // --------------------------------------------------------------
    00154
    00155     /** Name of the connection that NetLib will use unless the VPN
    00156      *  client overrides it by setting vpnConnProfileOverrideName
    00157      *  to a non-empty connection name string.  Watch out for the case
    00158      *  where the user inadvertently selected the VPN connection name
    00159      *  itself as the connection name for the network profile. VPN vendors
    00160      *  that choose to override this connection name, will likely wish
    00161      *  to save this connection name so that their destination connection.
    00162      */
    00163     Char                    defaultConnProfileName[cncProfileNameSize];
    00164
    00165     UInt32                  inReserved1;  /**< set to zero by this lib */
    00166     UInt32                  inReserved2;  /**< set to zero by this lib */
    00167
    00168
    00169     // --------------------------------------------------------------
    00170     // Outputs -- modify only if you wish to override the default
    00171     //            connection name!
    00172     // --------------------------------------------------------------
    00173
    00174     /** The VPN vendor may override the default connection name that NetLib
    00175      *  will use by setting this field to a non-empty string -- this string
    00176      *  MUST be a valid connection name that presently exists in the connection
    00177      *  panel!
    00178      *
    00179      *  If the VPN vendor presently does *not* wish to override the default
    00180      *  connection (based on user settings in the VPN vendor's configuration
    00181      *  UI), the VPN vendor should leave this field alone (don't modify
    00182      *  it in any way in this case to avoid conflicts with other VPN vendor
    00183      *  that may be currently installed on the same device).
    00184      */
    00185     Char                    vpnConnProfileOverrideName[cncProfileNameSize];
    00186   }
    00187 NetMasterClientEventVPNConnInstallType;
    00188
    00189
    00190 /** Increment this version # when adding fields to NetMasterClientEventInfoType,
    00191  *  except when just adding a new event data pointer to eventData
    00192  */
    00193 #define netMasterClientCurrentEventVersion      1
    00194
    00195 /**
    00196  * @brief This structure is passed as the 'detailsP' of the notification.
    00197  * @see Palm OS Notification Manager
    00198  */
    00199 typedef struct
    00200   {
    00201     // --------------------------------------------------------------
    00202     // Inputs
    00203     // --------------------------------------------------------------
    00204
    00205     /** Version of this structure -- all future versions MUST define
    00206       * backward compatible Event structures.
    00207       * NetMaster Library sets this to netMasterClientCurrentEventVersion
    00208       * at the time the library was built. */
    00209     UInt16                      version;
    00210
    00211     /** Event ID */
    00212     NetMasterClientEventEnum    eventID;
    00213
    00214     /** Data corresponding to the event ID */
    00215     union
    00216       {
    00217         /** genericEventDataP is for the convenience of the internal
    00218           * code only. */
    00219         void*                                   genericEventDataP;
    00220
    00221         /** For netMasterClientEventVPNConnInstall */
    00222         NetMasterClientEventVPNConnInstallType* vpnConnInstallP;
    00223
    00224       }
    00225     eventData;
    00226
    00227     UInt32                          inReserved1;    /**< Reserved values; Set to 0 by NetMaster library */
    00228     UInt32                          inReserved2;    /**< Reserved values; Set to 0 by NetMaster library */
    00229     UInt32                          inReserved3;    /**< Reserved values; Set to 0 by NetMaster library */
    00230     UInt32                          inReserved4;    /**< Reserved values; Set to 0 by NetMaster library */
    00231
    00232
    00233     // --------------------------------------------------------------
    00234     // Outputs - none for now
    00235     // --------------------------------------------------------------
    00236   }
    00237 NetMasterClientEventInfoType;
    00238
    00239
    00240 /** Special NetLibOpenConfig options passed to
    00241  *  NetMasterNetLibOpenWithOptions()
    00242  */
    00243 typedef UInt32    NetMasterNetLibOpenOptionsType;
    00244 enum
    00245   {
    00246     /** netMasterNetLibOpenOptAutoDismiss:
    00247      *
    00248      *  If set, auto-dismiss the progress dialog if error occurs
    00249      */
    00250     netMasterNetLibOpenOptAutoDismiss           = 0x00000001UL,
    00251
    00252
    00253     /** netMasterNetLibOpenOptBypassNetGuard:
    00254      *
    00255      *  If set, bypass the NetGuard feature -- for use by IOTA
    00256      *  service only!!!
    00257      *
    00258      *  IMPORTANT: *not* available on systems before Palm OS 5.0
    00259      */
    00260     //
    00261     // DOLATER \todo -- should this be in "protected" incs?
    00262     netMasterNetLibOpenOptBypassNetGuard        = 0x00000002UL,
    00263
    00264     /** If this flag is set by the client, then the connection will
    00265      *  be attempted only with the requested NetPref record, and the
    00266      *  fallback network profile, if any, will be ignored.
    00267      *
    00268      *  IMPORTANT: *not* available on systems before Palm OS 5.0
    00269      */
    00270     netMasterNetLibOpenOptPrimaryProfileOnly    = 0x00000004UL
    00271
    00272   };
    00273
    00274
    00275 /** Login priority values that may be passed to NetMasterSCNetAttach */
    00276 typedef UInt32    NetMasterLoginPriorityEnum;
    00277 enum
    00278   {
    00279     /** The vast majority of background and foreground applications SHOULD
    00280      *  ALWAYS use the Default login priority.  This allows Data Session
    00281      *  Control system software to optimize end-user experience
    00282      *  on the device by following specific data session
    00283      *  management rules requested by network operators.
    00284      */
    00285     netMasterLoginPriorityDefault           = 0,
    00286
    00287     /** The Low login priority is the *least* disruptive to existing data
    00288      *  sessions that were established with a different network service
    00289      *  profile than the one that you're requesting.
    00290      */
    00291     netMasterLoginPriorityLow               = 1,
    00292
    00293     /** The High login priority is the *most* disruptive to existing data
    00294      *  sessions that were established with a different network service
    00295      *  profile than the one that you're requesting.  This will typically
    00296      *  cause even active foreground data sessions to be torn down. This
    00297      *  priority is reserved for *internal use only*, and should be avoided
    00298      *  by other developers as its usage will typically break the data
    00299      *  session management model of the device, resulting in poor end-user
    00300      *  experience.
    00301      */
    00302     netMasterLoginPriorityHigh              = 2
    00303
    00304   };
    00305
    00306
    00307
    00308 /** Default value to pass as the anchorTimeoutSec parameter to NetMasterSCNetAttach */
    00309 #define netMasterAnchorTimeoutDefault     (-1)
    00310
    00311
    00312 // ----------------------------------------------------------------
    00313 /** Data Context type used by NetMasterSCNetAttach,
    00314  *  NetMasterSCNetDetach and friends.
    00315  */
    00316 // ----------------------------------------------------------------
    00317 typedef UInt32    NetMasterDataContextIDType;
    00318
    00319 // ----------------------------------------------------------------
    00320 /** Data Session type used by NetMasterSCSessionIDGetFromContext
    00321  *  and friends.
    00322  */
    00323 // ----------------------------------------------------------------
    00324 typedef UInt32    NetMasterDataSessionIDType;
    00325
    00326
    00327 #endif // _NET_MASTER_LIB_TYPES_H_

Top | Palm Developer Network © 2004-2008, Palm, Inc. All rights reserved. Generated on Fri Jun 13 10:06:54 2008 for Palm API Guide