API Guide Home (Online version only) |

# NetPrefLibTypes.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 NETPREF
    00007  */
    00008
    00009 /**
    00010  * @file    NetPrefLibTypes.h
    00011  * @version 1.0
    00012  * @date    12/12/2001
    00013  *
    00014  * @brief This file contains public data types exported by the NetPref Library
    00015  *
    00016  */
    00017
    00018 /*
    00019  * @private author   Vitaly Kruglikov
    00020  */
    00021
    00022
    00023 #ifndef _NET_PREF_LIB_TYPES_H_
    00024 #define _NET_PREF_LIB_TYPES_H_
    00025
    00026 /**
    00027  * @name Current library API version number
    00028  * @brief Returned by NetPrefLibVersionGet()
    00029  */
    00030 /*@{*/
    00031 #define netPrefLibVersionMajor    0
    00032 #define netPrefLibVersionMinor    2
    00033 #define netPrefLibVersionBugFix   0
    00034 /*@}*/
    00035
    00036 // Changes by minor version number:
    00037 //
    00038 // 0.1 -- original
    00039 // 0.2 -- added functions from NetPrefUtils.c to NetPrefLib API - this
    00040 //        change obsoletes most functions in NetPrefUtils.c. The obsoleted
    00041 //        functions in NetPrefUtils.c have been suppressed with conditional
    00042 //        compillation directive.
    00043
    00044
    00045
    00046 // Opaque structures
    00047 struct NetPrefContextTypeTag;
    00048 struct NetPrefRecordTypeTag;
    00049
    00050
    00051
    00052 /** Record field identifiers */
    00053 typedef UInt16 NetPrefRecFieldEnum;
    00054
    00055 /**
    00056  * @name Required Macros for Record Field Identifier
    00057  * @brief Define the required macros and then include NetPrefLibFieldInfoTable.h in
    00058  *        order to define the record field indentifier values (see
    00059  *        NetPrefLibFieldInfoTable.h for usage notes and currently defined fieldIDs)
    00060  */
    00061 /*@{*/
    00062 #define NetPrefRecFieldInfoPreamble()
    00063
    00064 #define NetPrefRecFieldInfoFIRST(fieldID, idValue)      fieldID = idValue,
    00065
    00066 #define NetPrefRecFieldInfoGrpStart(fieldID, idValue)   fieldID = idValue,
    00067
    00068 #define NetPrefRecFieldInfoGrpEnd(fieldID)              fieldID,
    00069
    00070 #define NetPrefRecFieldInfoExtended(fieldID, idValue, type, maxSize, flags, tagText, tagSize) \
    00071                                                         fieldID = idValue,
    00072
    00073 #define NetPrefRecFieldInfoLegacy(fieldID, idValue, type, maxSize, flags, tagText, tagSize) \
    00074                                                         fieldID = idValue,
    00075
    00076 #define NetPrefRecFieldInfoLAST(fieldID)                fieldID
    00077 /*@}*/
    00078
    00079 enum
    00080   {
    00081     // undefine this to insure the #include is always processed
    00082     #ifdef __NETPREFLIBFIELDINFOTABLE_H__
    00083         #undef __NETPREFLIBFIELDINFOTABLE_H__
    00084     #endif
    00085
    00086     // See NetPrefLibFieldInfoTable.h for usage notes
    00087     #include <NetPrefLibFieldInfoTable.h>
    00088
    00089     // In performing the following error check, we take advantage of
    00090     // our inside knowledge that NetPrefLibFieldInfoTable.h undefines
    00091     // the macros that we defined above
    00092     #ifdef NetPrefRecFieldInfoLAST
    00093       #error inclusion of NetPrefLibFieldInfoTable.h failed
    00094     #endif
    00095
    00096   };
    00097
    00098
    00099
    00100 /** NetPref Record ID type */
    00101 typedef UInt32  NetPrefRecIDType;
    00102
    00103
    00104
    00105 /** Field type identifiers */
    00106 typedef UInt16  NetPrefFieldTypeEnum;
    00107 enum
    00108   {
    00109     netPrefFieldTypeStr     = 1,  /**< ascii string -- size must include zero - terminator*/
    00110     netPrefFieldTypeUInt8   = 2,
    00111     netPrefFieldTypeUInt16  = 3,
    00112     netPrefFieldTypeUInt32  = 4,
    00113     netPrefFieldTypeBin     = 5,  /**< binary*/
    00114     netPrefFieldTypeZStrList= 6   /**< string list: list of zero-terminated strings terminated by empty string. Size must include zero-terminator*/
    00115   };
    00116
    00117 /** Service Medium identifiers (used with netPrefRecFieldSvcMediumAlias) */
    00118 typedef UInt16 NetPrefSvcMediumEnum;
    00119 enum
    00120   {
    00121     netPrefSvcMediumUnknown = 0,    /**< reserve 0*/
    00122     netPrefSvcMediumDialUp  = 1,    /**< basic dial-up - communication driver selection determines service attributes [DEFAULT]*/
    00123     netPrefSvcMediumDirect  = 2,    /**< basic, non-modem type of connection*/
    00124     netPrefSvcMedium1xRTT   = 3,    /**< CDMA 3G PDP service*/
    00125     netPrefSvcMediumGPRS    = 4,    /**< GSM 2.5G PDP service*/
    00126     netPrefSvcMediumQNC     = 5,    /**< CDMA Quick Net Connect*/
    00127     netPrefSvcMediumGISDN   = 6,    /**< GSM ISDN over CSD service*/
    00128     netPrefSvcMediumGCSD    = 7,    /**< GSM circuit switched data service (AKA wireless dial-up)*/
    00129     netPrefSvcMediumCCSD    = 8,    /**< CDMA circuit switched data service (AKA wireless dial-up)*/
    00130     netPrefSvcMediumOEM     = 9,    /**< This service is a place-holder for an external OEM plugin*/
    00131     netPrefSvcMediumLAST            /**< ALWAYS KEEP THIS ENTRY AT THE END!!!*/
    00132   };
    00133
    00134 /** Service Binding identifiers (use with netPrefRecFieldBinding); */
    00135 typedef UInt16 NetPrefSvcBindingEnum;
    00136 enum
    00137   {
    00138     netPrefSvcBindingUnknown  = 0,  /**< reserve 0*/
    00139     netPrefSvcBindingIOTA     = 1,  /**< Provisioned via IOTA*/
    00140     netPrefSvcBindingCCSM     = 2,  /**< Default Wireless profile based on the CCSM tables */
    00141     netPrefSvcBindingCustom   = 3,  /**< Created by user or "user agent" on behalf of the user [DEFAULT]*/
    00142     netPrefSvcBindingLAST           /**< ALWAYS KEEP THIS ENTRY AT THE END!!!*/
    00143   };
    00144
    00145
    00146 /** 1xRTT Tunneling identifiers (use with netPrefRecField1xRTTTunneling) */
    00147 typedef UInt16 NetPref1xRTTTunnelingEnum;
    00148 enum
    00149   {
    00150     netPref1xRTTTunnelingUnknown = 0,   /**< reserve 0*/
    00151     netPref1xRTTTunnelingReverse = 1,   /**< reverse tunneling*/
    00152     netPref1xRTTTunnelingForward = 2,   /**< forward tunneling*/
    00153     netPref1xRTTTunnelingLAST           /**< ALWAYS KEEP THIS ENTRY AT THE END!!!*/
    00154   };
    00155
    00156 /** Default 1xRTT Tunneling value */
    00157 #define netPref1xRTTTunnelingDefault  netPref1xRTTTunnelingReverse
    00158
    00159
    00160 /**
    00161  * Service Target identifiers used with NetPrefDefaultTargetGet()
    00162  * and NetPrefDefaultTargetSet().
    00163  *
    00164  * NOTE: These values need to correlate with NetPrefSvcGatewayType.
    00165  *
    00166  * IMPORTANT: These settings are to be used
    00167  * for carrier-provisioned services only, and are applied by the
    00168  * system's configurator app!!!  Others MUST treat these settings
    00169  * as read-only!
    00170  */
    00171 typedef UInt16 NetPrefSvcTargetEnum;
    00172 enum
    00173   {
    00174     netPrefSvcTargetUnknown   = 0,  /**< reserve 0*/
    00175     netPrefSvcTargetInternet  = 1,  /**< provides access to the Internet*/
    00176     netPrefSvcTargetWAP       = 2,  /**< provides access to WAP*/
    00177     netPrefSvcTargetReserved1 = 3,  /**< reserved*/
    00178     netPrefSvcTargetMMS       = 4,  /**< provides access to MMS*/
    00179     netPrefSvcTargetBrowser   = 5,  /**< provides access to Web via web browser*/
    00180     netPrefSvcTargetMail      = 6,  /**< provides access to e-mail*/
    00181     netPrefSvcTargetIM        = 7,  /**< provides access to Instant Messaging*/
    00182     netPrefSvcTargetDownloads = 8,  /**< provides access to Downloads*/
    00183     netPrefSvcTargetCorporate = 9,  /**< provides access to Corporate network*/
    00184     netPrefSvcTargetPictureMail = 10, /**< provides access to Picture Mail*/
    00185     netPrefSvcTargetLAST            /**< ALWAYS KEEP THIS ENTRY AT THE END!!!*/
    00186   };
    00187
    00188 /** Record field view attributes bitwise-or'ed together */
    00189 typedef UInt32  NetPrefRecFieldViewType;
    00190
    00191 /** @name Record File View Attributes */
    00192 /*@{*/
    00193 #define netPrefRecFieldViewRead     0x00000001UL  /**< read allowed by application*/
    00194 #define netPrefRecFieldViewWrite    0x00000002UL  /**< write allowed by application*/
    00195 #define netPrefRecFieldViewVisible  0x00000004UL  /**< field value is user-visible*/
    00196 #define netPrefRecFieldViewEditable 0x00000008UL  /**< field value is user-editable*/
    00197   /** Field value is stored exernally -- such as in the CCSM table, radio module's
    00198    *  flash memory, etc., i.e. not in the NetPref database
    00199    */
    00200 #define netPrefRecFieldViewExternal 0x00000010UL
    00201 #define netPrefRecFieldViewCache    0x00000020UL  /**< the external field value is cached locally*/
    00202 #define netPrefRecFieldViewPrivate  0x00000040UL  /**< PRESENTLY NOT RESPECTED; If set, do not display the actual value to the user*/
    00203 /*@}*/
    00204
    00205 // WARNING: THIS CONSTANT IS FOR INTERNAL USE ONLY -- IT WILL CHANGE
    00206 // IN FUTURE VERSIONS!!! (used for error-checking only).
    00207 #define netPrefRecFieldViewCurrentlyValidFlags      \
    00208                     (   netPrefRecFieldViewRead     \
    00209                       | netPrefRecFieldViewWrite    \
    00210                       | netPrefRecFieldViewVisible  \
    00211                       | netPrefRecFieldViewEditable \
    00212                       | netPrefRecFieldViewExternal \
    00213                       | netPrefRecFieldViewCache    \
    00214                       | netPrefRecFieldViewPrivate)
    00215
    00216 /** Special value to pass in the flagsToClear parameter to NetPrefRecFieldViewSet in order to clear all field view flags */
    00217 #define netPrefRecFieldViewClearAll 0xFFFFFFFFUL
    00218
    00219 /** Record field attributes (retrieved via NetPrefRecFieldAttrsGet) */
    00220 typedef UInt32  NetPrefRecFieldAttrType;
    00221
    00222 /** @name Record File Attributes */
    00223 /*@{*/
    00224     /** R/O: set if the field's
    00225      * data or flags are part of the record's field
    00226      * set.
    00227      */
    00228     #define netPrefRecFieldAttrInSet    0x10000000UL
    00229
    00230     /** R/O: set if the field's
    00231      * data or flags have been modified in the current
    00232      * instance of the record object
    00233      */
    00234     #define netPrefRecFieldAttrDirty    0x20000000UL
    00235 /*@}*/
    00236
    00237 /** Special values used with netPrefRecFieldCloseWaitTime.  Other, standard,
    00238  *  values are expressed in milliseconds.
    00239  *  IMPORTANT: Beginning with Palm OS 5.0, netPrefRecFieldInactivityTimer
    00240  *  must be used to configure the idle timeout of the TCP/IP stack. The
    00241  *  "CloseWait" settting is used to control NetLib's CloseWait behavior
    00242  *  only
    00243  */
    00244 typedef UInt32 NetPrefNetCloseWaitEnum; // was NetPrefNetTimeoutEnum
    00245 enum
    00246   {
    00247     /** Use this value to configure the network interface to be shut down
    00248      * when the device (i.e. LCD screen) powers off.
    00249      */
    00250     netPrefNetCloseWaitEndOnPowerOff    = 0xffffffffUL, // was netPrefNetTimeoutOnPowerOff
    00251
    00252     /** Use this value to configure the network interface to *not* be shut down
    00253      * when the device (i.e. LCD screen) powers off.
    00254      */
    00255     netPrefNetCloseWaitMaintainSession  = 0xfffffffeUL, // was netPrefNetTimeoutOnWirelessOff
    00256
    00257     /** Use this value to configure the CloseWait behavior with the carrier-
    00258      * default value.
    00259      */
    00260     netPrefNetCloseWaitCarrierDefault   = 0xfffffffdUL  // was netPrefNetTimeoutCarrierDefault
    00261   };
    00262
    00263
    00264 /** Special values used with netPrefRecFieldInactivityTimer.
    00265  *  Other, standard, values are expressed in seconds.
    00266  */
    00267 typedef UInt16 NetPrefNetIdleTimeoutEnum;
    00268 enum
    00269   {
    00270     netPrefNetIdleTimeoutNever          = (UInt16) 0    /**< Never time out due to data idleness*/
    00271   };
    00272
    00273
    00274
    00275 /** Record protection settings -- used with netPrefRecFieldRecProtection */
    00276 typedef UInt32 NetPrefRecProtectionType;
    00277 enum
    00278   {
    00279     /** Record deletion options*/
    00280     netPrefRecProtectionDeletionMask                  = 0x00000007UL,
    00281     netPrefRecProtectionDeletionAfterWarning          = 0x0UL,
    00282     netPrefRecProtectionDeletionNotAllowed            = 0x1UL,
    00283
    00284
    00285     /** Duplication options*/
    00286     netPrefRecProtectionDuplicationMask               = (0x7UL << 3),
    00287     netPrefRecProtectionDuplicationAllowed            = (0x0UL << 3),
    00288     netPrefRecProtectionDuplicationNotAllowed         = (0x1UL << 3),
    00289
    00290
    00291     /** Editing options*/
    00292     netPrefRecProtectionEditingMask                   = (0x7UL << 6),
    00293     netPrefRecProtectionEditingAllowed                = (0x0UL << 6),
    00294     netPrefRecProtectionEditingNotAllowed             = (0x1UL << 6),
    00295     netPrefRecProtectionEditingAfterWarning           = (0x2UL << 6)
    00296   };
    00297
    00298
    00299
    00300 /**
    00301  * Record Service gateway type -- used with netPrefRecFieldSvcGatewayType;
    00302  * 1 or more values can be bitwise or'ed together to mark
    00303  * a record as supporting those gateway types; absense of
    00304  * any service type falgs implies Internet.
    00305  *
    00306  * NOTE: These values need to correlate with NetPrefSvcTargetEnum.
    00307  *
    00308  * IMPORTANT: These settings are to be used
    00309  * for carrier-provisioned services only, and are applied by the
    00310  * system's configurator app!!!  Others MUST treat these settings
    00311  * as read-only!
    00312  */
    00313 typedef UInt32 NetPrefSvcGatewayType;
    00314 enum
    00315   {
    00316     netPrefSvcGatewayUnknown        = 0UL,          /**< reserved*/
    00317     netPrefSvcGatewayInternet       = 0x00000001UL, /**< Generic Internet "gateway"*/
    00318     netPrefSvcGatewayWAP            = 0x00000002UL, /**< Generic WAP gateway*/
    00319     netPrefSvcGatewayPrivate        = 0x00000004UL, /**< Application-specific "gateway"*/
    00320     netPrefSvcGatewayMMS            = 0x00000008UL, /**< Generic MMS "gateway"*/
    00321     netPrefSvcGatewayBrowser        = 0x00000010UL, /**< Web via web browser*/
    00322     netPrefSvcGatewayMail           = 0x00000020UL, /**< e-mail*/
    00323     netPrefSvcGatewayIM             = 0x00000040UL, /**< Instant Messaging*/
    00324     netPrefSvcGatewayDownloads      = 0x00000080UL, /**< Downloads*/
    00325     netPrefSvcGatewayCorporate      = 0x00000100UL, /**< Corporate network*/
    00326     netPrefSvcGatewayPictureMail    = 0x00000200L,  /**< Picture Mail*/
    00327
    00328     netPrefSvcGatewayLAST             /**< ALWAYS KEEP THIS ENTRY AT THE END!!!*/
    00329   };
    00330
    00331
    00332 /**
    00333  * @brief NetPrefGPRSQOSType -- GPRS Quality Of Service (QOS) info
    00334  */
    00335 typedef struct
    00336   {
    00337     // IMPORTANT: maintain this structure at fixed size; remove
    00338     // space for new fields from the reserved fields, making sure
    00339     // to adjust the reserved field size so the overall structure
    00340     // size is preserved exactly.  Use reserved space wisely :-)
    00341
    00342     // NOTE: "ccsmCS_QOS..." in the following comments refers to Hanspring-
    00343     // internal data structures.  Developer support will need to provide
    00344     // clarification for the use of these fields.
    00345
    00346     Int8      qosReqPrecedenceClass;  /**< see ccsmCS_QOSReqPrecClassField*/
    00347     Int8      qosReqDelayClass;       /**< see ccsmCS_QOSReqDelayClassField*/
    00348     Int8      qosReqReliabilityClass; /**< see ccsmCS_QOSReqRelClassField*/
    00349     Int8      qosReqPeakThruClass;    /**< see ccsmCS_QOSReqPeakThruClassField*/
    00350     Int8      qosReqMeanThruClass;    /**< see ccsmCS_QOSReqMeanThruClassField*/
    00351     Int8      qosMinPrecedenceClass;  /**< see ccsmCS_QOSMinPrecClassField*/
    00352     Int8      qosMinDelayClass;       /**< see ccsmCS_QOSMinDelayClassField*/
    00353     Int8      qosMinReliabilityClass; /**< see ccsmCS_QOSMinRelClassField*/
    00354     Int8      qosMinPeakThruClass;    /**< see ccsmCS_QOSMinPeakThruClassField*/
    00355     Int8      qosMinMeanThruClass;    /**< see ccsmCS_QOSMinMeanThruClassField*/
    00356     Int8      pdpDataCompression;     /**< see ccsmCS_PDPDataComprField*/
    00357     Int8      pdpHeaderCompression;   /**< see ccsmCS_PDPHeaderComprField*/
    00358
    00359     UInt32    reserved[4];            /**< Reserved by Handspring -- init to zero*/
    00360   }
    00361 NetPrefGPRSQOSType;
    00362
    00363
    00364 /** Options for NetPrefRecFieldSetDefineStd and NetPrefRecFieldSetDefine */
    00365 typedef UInt32    NetPrefFieldSetDefineOptionsType;
    00366 enum
    00367   {
    00368     netPrefFieldSetDefineOptionNone = 0,        /**< Pass this value for "no options"*/
    00369
    00370     // If set, NetPrefRecFieldSetDefineStd and NetPrefRecFieldSetDefine
    00371     // will temporarily keep around the data of out-of-set fields; however,
    00372     // it will not save such data when saving the field; this feature
    00373     // is a convenience for the Network panel that allows the user to
    00374     // experiment with different connection mediuma (dial-up, direct, 3G, etc.)
    00375     // without losing the data that is in one service medium's field set,
    00376     // but not in another.
    00377     netPrefFieldSetDefineOptionKeepData = 0x00000001UL
    00378   };
    00379
    00380
    00381
    00382 // ----------------------------------------------------------------------------
    00383 // Fallback info -- used with netPrefRecFieldFallbackInfo
    00384 // ----------------------------------------------------------------------------
    00385
    00386 // NOTE: The Handspring NetMaster library implements the fallback logic.
    00387
    00388
    00389 /** Fallback algorithm */
    00390 typedef UInt8     NetPrefFallbackAlgrorithmEnum;
    00391 enum
    00392   {
    00393     /**  Basic algorithm: each time: try primary; if fails, try fallback; */
    00394     netPrefFallbackAlgrorithmBasic = 0,
    00395
    00396     /**
    00397      * Mutually exclusive, sticky algorithm: The primary and fallback record
    00398      * MUST be cross-linked -- each MUST specify the other as its fallback;
    00399      * both records MUST also be tagged with this algorithm.  Regardless of
    00400      * which of the cross-linked services is requested during login (unless
    00401      * "primary only" is requested -- see NetMaster API), the algorithm will
    00402      * attempt to connect with the one that succeeded last time. The first time
    00403      * or if both failed last time, it will try the requested service first. If
    00404      * the attempt fails, it will try the one specified as its fallback.
    00405      */
    00406     netPrefFallbackAlgrorithmMutexSticky = 1,
    00407
    00408
    00409
    00410     // ADD NEW VALUES *BEFORE* THIS ONE
    00411     netPrefFallbackAlgrorithmLAST
    00412   };
    00413
    00414
    00415 typedef UInt8 NetPrefFallbackStatusFlagsType;
    00416 enum
    00417   {
    00418     // If set, inidicates that NetPrefFallbackInfoType.status has
    00419     // been initialized.
    00420     netPrefFallbackStatusFlagInitialized = 0x01
    00421
    00422   };
    00423
    00424
    00425 /** Flags used in the "Mutex Sticky" fallback algoritm status structure. */
    00426 typedef UInt16 NetPrefMutexStickyFBAStatusEnum;
    00427 enum
    00428   {
    00429     netPrefMutexStickyFBAStatusUnknown      = 0, /**< Indicates that the last login status of the corresponding network service is unknown.*/
    00430
    00431     netPrefMutexStickyFBAStatusFailed       = 1, /**< Indicates that the last login attempt using the corresponding network service failed.*/
    00432
    00433     netPrefMutexStickyFBAStatusSucceeded    = 2  /**< Indicates that the last login attempt using the corresponding network service succeeded.*/
    00434   };
    00435
    00436
    00437 /**
    00438  * @brief Fallback info structure
    00439  */
    00440 typedef struct
    00441   {
    00442     /** Fallback algorithm ID.
    00443      *
    00444      * IMPORTANT: when changing fallback algorithm, the
    00445      * caller MUST zero-initialize the rest of the NetPrefFallbackInfoType
    00446      * structure.
    00447      */
    00448     NetPrefFallbackAlgrorithmEnum   algorithm;
    00449
    00450     /** Fallback algoritm status. There is a field here for every fallback
    00451      * algorithm that requires status to be maintained.
    00452      *
    00453      * THIS STATUS STRUCTURE IS FOR USE BY THE HANDSPRING NetMaster LIBRARY
    00454      * ONLY!!!
    00455      */
    00456     NetPrefFallbackStatusFlagsType  fbStatusFlags;
    00457
    00458     union
    00459       {
    00460         /** Status for netPrefFallbackAlgrorithmMutexSticky fallback algorithm */
    00461         struct NetPrefMutexStickyFBAStatusTypeTag
    00462           {
    00463             NetPrefMutexStickyFBAStatusEnum  statusID;
    00464           }
    00465         mutexSticky;
    00466
    00467       }
    00468     status;
    00469   }
    00470 NetPrefFallbackInfoType;
    00471
    00472
    00473 // ----------------------------------------------------------------------------
    00474 // Platform IDs
    00475 // ----------------------------------------------------------------------------
    00476 typedef UInt16    NetPrefPlatformEnum;
    00477 enum
    00478   {
    00479     netPrefPlatformUnknown    = 0,
    00480
    00481     netPrefPlatformGSM        = 1,
    00482     netPrefPlatformCDMA       = 2,
    00483
    00484     netPrefPlatformLAST
    00485   };
    00486
    00487
    00488
    00489 /**
    00490  * Max size of a phone number, *not including* zero-terminator
    00491  */
    00492  #define netPrefMaxPhoneStringSize 80
    00493
    00494
    00495
    00496 #endif // _NET_PREF_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