API Guide Home (Online version only) |

# NetPrefLibrary.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    NetPrefLibrary.h
    00011  * @version 1.0
    00012  * @date    06/24/2002
    00013  *
    00014  * @brief   This is the main header file for the NetPref Library.
    00015  *
    00016  * USAGE MODEL:
    00017  * The model for using the NetPref library is that you "link" it
    00018  * in when needed and "unlink" it as you're done -- i.e. we don't
    00019  * leave it permanently installed as we do with some other libraries.
    00020  * This helps us avoid some unpleasant HotSync issues (such as trying
    00021  * to install over a protected database).  For examples of linking
    00022  * and unlinking, grep for calls to  NetPrefUtilNetPrefLibLink and
    00023  * NetPrefUtilNetPrefLibUnlink in NetworkPanel.c (Network panel src
    00024  * folder).  NetPrefUtilNetPrefLibLink and NetPrefUtilNetPrefLibUnlink
    00025  * are defined in Viewer\Libraries\NetPref\Public\Util\NetPrefUtils.c/h --
    00026  * you may include the .c file with your code, or just copy and paste out
    00027  * of those functions.
    00028  *
    00029  */
    00030
    00031 /*
    00032  * @author   Vitaly Kruglikov
    00033  *
    00034  * History:
    00035  *    12-Dec-2001   vmk   Created by Vitaly Kruglikov
    00036  *    24-Jun-2002   vmk   Removed inclusion of private header file
    00037  *                        OSServices.h.
    00038  * <hr>
    00039  */
    00040
    00041 #ifndef _NET_PREF_LIBRARY_H_
    00042 #define _NET_PREF_LIBRARY_H_
    00043
    00044
    00045 #include <NetPrefLibTarget.h>
    00046 #include <NetPrefLibTraps.h>
    00047 #include <NetPrefLibErrors.h>
    00048 #include <NetPrefLibTypes.h>
    00049
    00050
    00051
    00052 #ifdef BUILDING_NET_PREF_LIB_DISPATCH_TABLE
    00053   #define NETPREF_LIB_TRAP(trapNum)
    00054 #else
    00055   #define NETPREF_LIB_TRAP(trapNum) SYS_TRAP(trapNum)
    00056 #endif
    00057
    00058 #ifdef __cplusplus
    00059 extern "C" {
    00060 #endif
    00061
    00062 /** Standard library open routine.
    00063  *
    00064  *  @param refnum:  IN:  Library reference number
    00065  *  @retval Err     Library error code
    00066  */
    00067 extern Err NetPrefLibOpen (UInt16 refNum, struct NetPrefContextTypeTag** cxtPP)
    00068     NETPREF_LIB_TRAP (sysLibTrapOpen);
    00069
    00070 /** Standard library close routine.
    00071  *
    00072  *  @param refnum:  IN:  Library reference number
    00073  *  @retval Err     Library error code
    00074  */
    00075 extern Err NetPrefLibClose (UInt16 refNum, struct NetPrefContextTypeTag* cxtP)
    00076     NETPREF_LIB_TRAP (sysLibTrapClose);
    00077
    00078 /** Standard library sleep routine.
    00079  *
    00080  *  @param refnum:  IN:  Library reference number
    00081  *  @retval Err     Library error code
    00082  */
    00083 extern Err NetPrefLibSleep (UInt16 refNum)
    00084     NETPREF_LIB_TRAP (sysLibTrapSleep);
    00085
    00086 /** Standard library wake routine.
    00087  *
    00088  *  @param refnum:  IN:  Library reference number
    00089  *  @retval Err     Library error code
    00090  */
    00091 extern Err NetPrefLibWake (UInt16 refNum)
    00092     NETPREF_LIB_TRAP (sysLibTrapWake);
    00093
    00094 /** Get Library API Version number.
    00095  *
    00096  *  @param refnum:          IN:  Library reference number
    00097  *  @param majorVerP:       OUT: Major version number
    00098  *  @param minorVerP:       OUT: Minor version number
    00099  *  @param bugFixVerP:      OUT: Bug fix version number
    00100  *  @retval Err             NetPref Library error code
    00101  */
    00102 extern Err
    00103 NetPrefLibVersionGet (UInt16 refNum, UInt32* majorVerP, UInt32* minorVerP,
    00104                       UInt32* bugFixVerP)
    00105     NETPREF_LIB_TRAP (netPrefLibTrapVersionGet);
    00106
    00107
    00108 /** Retrieve the count of records in the NetPref database */
    00109 extern Err
    00110 NetPrefRecCountGet (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
    00111                     UInt16* countP)
    00112     NETPREF_LIB_TRAP (netPrefLibTrapRecCountGet);
    00113
    00114
    00115 /** Get record ID given the 0-based record index, which must be
    00116  *  in range of 0..NetPrefRecCountGet()-1.
    00117  *  The record's index may change following the NetPrefRecSave opeation.
    00118  */
    00119 extern Err
    00120 NetPrefRecIDGetByIndex (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
    00121                         UInt16 recIndex, UInt32* recIDP)
    00122     NETPREF_LIB_TRAP (netPrefLibTrapRecIDGetByIndex);
    00123
    00124 /** Get record index given the unique record ID, which must be
    00125  *   non-zero.
    00126  *   The record's index may change following the NetPrefRecSave opeation.
    00127  */
    00128 extern Err
    00129 NetPrefRecIndexGetByID (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
    00130                         UInt32 recID, UInt16* recIndexP)
    00131     NETPREF_LIB_TRAP (netPrefLibTrapRecIndexGetByID);
    00132
    00133
    00134 /** Create a new record object.  Pass a non-zero dupRecID to duplicate
    00135  *   an existing record.
    00136  *   The caller is responsible for calling NetPrefRecRelease() to
    00137  *   dispose of the temporary resources associated with the loaded record
    00138  */
    00139 extern Err
    00140 NetPrefRecNew (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
    00141                UInt32 dupRecID, struct NetPrefRecordTypeTag** recPP)
    00142     NETPREF_LIB_TRAP (netPrefLibTrapRecNew);
    00143
    00144
    00145 /** Load an existing record into memory; the caller is responsible for
    00146  *   calling NetPrefRecRelease() to dispose of the temporary resources
    00147  *   associated with the loaded record.
    00148  */
    00149 extern Err
    00150 NetPrefRecLoad (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
    00151                 UInt32 recID, struct NetPrefRecordTypeTag** recPP)
    00152     NETPREF_LIB_TRAP (netPrefLibTrapRecLoad);
    00153
    00154
    00155 /** Call this to check if there was an error from application of a binding
    00156  *   (such as CCSM) to the record.
    00157  */
    00158 extern Err
    00159 NetPrefRecBindingErrorGet (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
    00160                            struct NetPrefRecordTypeTag* recP)
    00161     NETPREF_LIB_TRAP (netPrefLibTrapRecBindingErrorGet);
    00162
    00163
    00164 /** Dispose of the temporary resources associated with a record that
    00165  *   was created or loaded via NetPrefRecNew or NetPrefRecLoad.
    00166  *   It's the library client's (application's) responsibility to
    00167  *   call this function to free up the memory.  Resets *recPP to NULL.
    00168  */
    00169 extern Err
    00170 NetPrefRecRelease (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
    00171                    struct NetPrefRecordTypeTag** recPP)
    00172     NETPREF_LIB_TRAP (netPrefLibTrapRecRelease);
    00173
    00174
    00175 /** Save the record to the database, moving it to a new sorted position
    00176  *   if necessary.  For existing records, if any fields
    00177  *   have been changed, you must call NetPrefRecSave in order to
    00178  *   get an accurate record index.
    00179  */
    00180 extern Err
    00181 NetPrefRecSave (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
    00182                 struct NetPrefRecordTypeTag* recP)
    00183     NETPREF_LIB_TRAP (netPrefLibTrapRecSave);
    00184
    00185
    00186 /** Check if this record object is "attached" to the database.  A record
    00187  *   that has been created via NetPrefRecObjAlloc and never saved is
    00188  *   not "attached" to the database.
    00189  */
    00190 extern Boolean
    00191 NetPrefRecIsAttached (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
    00192                       struct NetPrefRecordTypeTag* recP)
    00193     NETPREF_LIB_TRAP (netPrefLibTrapRecIsAttached);
    00194
    00195
    00196
    00197 /** Allocate a "blank slate" record object.  This record will not be "attached"
    00198  *   to the database until saved via NetPrefRecSave.  Intended for use with
    00199  *   NetPrefRecObjCopy, and by internal code.
    00200  */
    00201 extern Err
    00202 NetPrefRecObjAlloc (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
    00203                     struct NetPrefRecordTypeTag** recPP)
    00204     NETPREF_LIB_TRAP (netPrefLibTrapRecObjAlloc);
    00205
    00206 /** Copy the contents of the source record object to the destination
    00207  *   record object.  This is useful for implementing revert functionality.
    00208  */
    00209 extern Err
    00210 NetPrefRecObjCopy (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
    00211                    struct NetPrefRecordTypeTag* srcRecP,
    00212                    struct NetPrefRecordTypeTag* dstRecP)
    00213     NETPREF_LIB_TRAP (netPrefLibTrapRecObjCopy);
    00214
    00215
    00216 /** Get the unique record ID of the record's entry in the database.
    00217  *
    00218  *  WARNING:
    00219  *   It is an error to call NetPrefRecIDGet on records that have not been
    00220  *   attached to the database -- see NetPrefRecIsAttached().
    00221  *
    00222  */
    00223 extern Err
    00224 NetPrefRecIDGet (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
    00225                  struct NetPrefRecordTypeTag* recP, UInt32* recIDP)
    00226     NETPREF_LIB_TRAP (netPrefLibTrapRecIDGet);
    00227
    00228 /** Get the 0-based index of the record's entry in the database.
    00229  *  The record's index may change following the NetPrefRecSave opeation.
    00230  *
    00231  *  WARNING:
    00232  *   It is an error to call NetPrefRecIndexGet on records that have not been
    00233  *   attached to the database -- see NetPrefRecIsAttached().
    00234  */
    00235 extern Err
    00236 NetPrefRecIndexGet (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
    00237                     struct NetPrefRecordTypeTag* recP, UInt16* recIndexP)
    00238     NETPREF_LIB_TRAP (netPrefLibTrapRecIndexGet);
    00239
    00240
    00241 /** Delete the given record from the database; if the record is bound
    00242  *   to another, such as that stored in non-volatile memory of the radio
    00243  *   module, will delete the primary record as well.  If the client
    00244  *  has a memory object representing the record being deleted, the client
    00245  *   is still responsible for releasing it via NetPrefRecRelease().
    00246  *
    00247  */
    00248 extern Err
    00249 NetPrefRecDelete (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
    00250                   UInt32 recID)
    00251     NETPREF_LIB_TRAP (netPrefLibTrapRecDelete);
    00252
    00253 /** Get a pointer to a given record field; upon successful return,
    00254  *   the value of the field is to be interpreted as follows:
    00255  *
    00256  *    NULL    -- field value is not assigned
    00257  *    non-NULL -- field value has been assigned, the
    00258  *                value must be treated as read-only!
    00259  *  Field view depends on the Medium and Binding of the record
    00260  */
    00261 extern Err
    00262 NetPrefRecFieldGet (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
    00263                    struct NetPrefRecordTypeTag* recP,
    00264                    NetPrefRecFieldEnum recFieldID, void** fieldValuePP,
    00265                    UInt32* fieldLenP, NetPrefRecFieldViewType* viewFlagsP)
    00266     NETPREF_LIB_TRAP (netPrefLibTrapRecFieldGet);
    00267
    00268
    00269 /** Get the attributes of a field */
    00270 extern Err
    00271 NetPrefRecFieldAttrsGet (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
    00272                          struct NetPrefRecordTypeTag* recP,
    00273                          NetPrefRecFieldEnum recFieldID,
    00274                          NetPrefRecFieldAttrType* fieldAttrsP)
    00275     NETPREF_LIB_TRAP (netPrefLibTrapRecFieldAttrsGet);
    00276
    00277
    00278 /** NetPrefRecFieldSet:
    00279  *  Set the value of the field.  The library will duplicate the value
    00280  *   passed in fieldValueP. Set fieldValueP to NULL to delete the
    00281  *   field's data. NOTE: setting a field invalidates any cached
    00282  *   pointer that you may already have to the field's value.
    00283  *
    00284  *   NOTES:
    00285  *    1) Field must be in record's field-set before you can set its
    00286  *       data or view flags.
    00287  *
    00288  *    2) String field values MUST be zero-terminated and the fieldLen
    00289  *       MUST include the zero-terminator.
    00290  *
    00291  *    3) If a change results, the record object will be marked as dirty
    00292  *
    00293  */
    00294 extern Err
    00295 NetPrefRecFieldSet (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
    00296                     struct NetPrefRecordTypeTag* recP,
    00297                     NetPrefRecFieldEnum recFieldID, void* fieldValueP,
    00298                     UInt32 fieldLen)
    00299     NETPREF_LIB_TRAP (netPrefLibTrapRecFieldSet);
    00300
    00301
    00302 /** Set the view flags of the field.  If a change results, the record
    00303  *  object will be marked as dirty.
    00304  *
    00305  *  NOTES:
    00306  *    1) Field must be in record's field-set before you can set its
    00307  *       data or view flags.
    00308  *
    00309  *    2) If a change results, the record object will be marked as dirty
    00310  */
    00311 extern Err
    00312 NetPrefRecFieldViewSet (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
    00313                         struct NetPrefRecordTypeTag* recP,
    00314                         NetPrefRecFieldEnum recFieldID,
    00315                         NetPrefRecFieldViewType flagsToClear,
    00316                         NetPrefRecFieldViewType flagsToSet)
    00317     NETPREF_LIB_TRAP (netPrefLibTrapRecFieldViewSet);
    00318
    00319
    00320
    00321 /** NetPrefRecReadOnlyOverrideStart/End: Increment/decrement the
    00322  * record object's readOnlyOverrideCount variable.  The two
    00323  * function calls must be balanced -- i.e., ...End must be called
    00324  * exactly as many times as ...Start regardless of other events,
    00325  * such as errors. If greater than zero, NetPrefRecFieldSet
    00326  * will allow the field to be set regardless of the record's read-only
    00327  * status.  This permits internal record "loaders" to initialize record
    00328  * fields regardless of the read-only status of the fields being loaded.
    00329  */
    00330 extern void
    00331 NetPrefRecReadOnlyOverrideStart (UInt16 refNum,
    00332                                  struct NetPrefContextTypeTag* cxtP,
    00333                                  struct NetPrefRecordTypeTag* recP)
    00334     NETPREF_LIB_TRAP (netPrefLibTrapRecReadOnlyOverrideStart);
    00335
    00336 extern void
    00337 NetPrefRecReadOnlyOverrideEnd (UInt16 refNum,
    00338                                struct NetPrefContextTypeTag* cxtP,
    00339                                struct NetPrefRecordTypeTag* recP)
    00340     NETPREF_LIB_TRAP (netPrefLibTrapRecReadOnlyOverrideEnd);
    00341
    00342
    00343 /** Define the field set associated with the record; fields that
    00344  * are not in the new field will be removed from the record
    00345  * object.  For fields in the new field set, existing data will
    00346  * be left alone.
    00347  *
    00348  * You may pass a pointer to new
    00349  * NetPrefRecFieldViewType in initialViewFlagsP to set those
    00350  * view flags in all the fields in the new field set (or pass
    00351  * NULL to ignore this parameter and leave field view flags
    00352  * at their old values).
    00353  *
    00354  * To remove all fields from the field set, set newNumFields to 0
    00355  * and recFieldIDArrayP to NULL;
    00356  */
    00357 extern Err
    00358 NetPrefRecFieldSetDefine (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
    00359                           struct NetPrefRecordTypeTag* recP,
    00360                           NetPrefRecFieldEnum* recFieldIDArrayP,
    00361                           UInt16 newNumFields,
    00362                           NetPrefRecFieldViewType* initialViewFlagsP,
    00363                           NetPrefFieldSetDefineOptionsType options)
    00364     NETPREF_LIB_TRAP (netPrefLibTrapRecFieldSetDefine);
    00365
    00366
    00367
    00368 /** Add a field to the Field-set of a given record and, optionally, set its
    00369  * view flags (set initialViewFlagsP to NULL to leave the field's view flags
    00370  * alone).
    00371  *
    00372  * NOTE: If the field was already part of the record's field-set, the field's
    00373  * data will be preserved.  However, the field's view flags will be overwritten
    00374  * with those supplied via initialViewFlagsP if initialViewFlagsP is not NULL.
    00375  */
    00376 extern Err
    00377 NetPrefRecFieldAddToSet (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
    00378                          struct NetPrefRecordTypeTag* recP,
    00379                          NetPrefRecFieldEnum recFieldID,
    00380                          NetPrefRecFieldViewType* initialViewFlagsP)
    00381     NETPREF_LIB_TRAP (netPrefLibTrapRecFieldAddToSet);
    00382
    00383
    00384 /** Define a "standard" field set based on Service Medium value -- basically,
    00385  * this is what the New Network Preference panel uses when it creates new
    00386  * services.
    00387  *
    00388  * You may pass a pointer to new
    00389  * NetPrefRecFieldViewType in initialViewFlagsP to set the
    00390  * view flags of all the fields in the new field set (or pass
    00391  * NULL for default flags).
    00392  */
    00393 extern Err
    00394 NetPrefRecFieldSetDefineStd (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
    00395                              struct NetPrefRecordTypeTag* recP,
    00396                              NetPrefSvcMediumEnum svcMedium,
    00397                              NetPrefRecFieldViewType* initialViewFlagsP,
    00398                              NetPrefFieldSetDefineOptionsType options)
    00399     NETPREF_LIB_TRAP (netPrefLibTrapRecFieldSetDefineStd);
    00400
    00401
    00402 /** Get the current field set of the record object.  The array
    00403  * recFieldIDArrayP MUST have enough entries (numEntriesAvailable)
    00404  * to receive the field ID's of all fields in the field set.
    00405  * The actual count of fields in the field set is returned in
    00406  * *numFieldsInSetP.
    00407  * To simply get the count of fields in the field set, without
    00408  * returning the actual field ID's, set numEntriesAvailable to 0
    00409  * and recFieldIDArrayP to NULL;
    00410  */
    00411 extern Err
    00412 NetPrefRecFieldSetGet (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
    00413                        struct NetPrefRecordTypeTag* recP,
    00414                        NetPrefRecFieldEnum* recFieldIDArrayP,
    00415                        UInt16 numEntriesAvailable, UInt16* numFieldsInSetP)
    00416     NETPREF_LIB_TRAP (netPrefLibTrapRecFieldSetGet);
    00417
    00418 /** Check if the record is dirty (has been modified by the client)
    00419  */
    00420 extern Err
    00421 NetPrefRecIsDirty (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
    00422                     struct NetPrefRecordTypeTag* recP,
    00423                     UInt8* isDirtyP)
    00424     NETPREF_LIB_TRAP (netPrefLibTrapRecIsDirty);
    00425
    00426
    00427 /** Reset all of the record's "dirty" flags.  NOTE: NetPrefRecSave will not
    00428  * save a record that is not marked as "dirty"
    00429  */
    00430 extern void
    00431 NetPrefRecDirtyFlagsReset (UInt16 refNum,
    00432                            struct NetPrefContextTypeTag* cxtP,
    00433                            struct NetPrefRecordTypeTag* recP)
    00434     NETPREF_LIB_TRAP (netPrefLibTrapRecDirtyFlagsReset);
    00435
    00436
    00437 /** Mark a record as "dirty" so it would be saved by NetPrefRecSave.
    00438  */
    00439 extern void
    00440 NetPrefRecMarkDirty (UInt16 refNum,
    00441                      struct NetPrefContextTypeTag* cxtP,
    00442                      struct NetPrefRecordTypeTag* recP)
    00443     NETPREF_LIB_TRAP (netPrefLibTrapRecMarkDirty);
    00444
    00445
    00446 /** Get the default service ID for the given target
    00447  */
    00448 extern Err
    00449 NetPrefDefaultTargetGet (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
    00450                          NetPrefSvcTargetEnum svcTarget, UInt32* recIDP)
    00451     NETPREF_LIB_TRAP (netPrefLibTrapDefaultTargetGet);
    00452
    00453
    00454 /** Set the given service as the default service for the given target type;
    00455  * Set recID to 0 (zero) to clear the default for that target type.
    00456  * (WAP, Internet, all, etc.)
    00457  */
    00458 extern Err
    00459 NetPrefDefaultTargetSet (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
    00460                          NetPrefSvcTargetEnum svcTarget, UInt32 recID)
    00461     NETPREF_LIB_TRAP (netPrefLibTrapDefaultTargetSet);
    00462
    00463
    00464 /** Update the NetPref database from the Non-Volatile storage of the radio,
    00465  * if any.  This should be called by the IOTA application after provisioning,
    00466  * as well as when the wireless mode is turned on.  This function is optimized
    00467  * to quickly determine if synchronization is necessary, and skip it if not.
    00468  * Set "force" to true to skip optimization and force synchronization.
    00469  */
    00470 extern Err
    00471 NetPrefUpdateFromRadioNV (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
    00472                           Boolean force)
    00473     NETPREF_LIB_TRAP (netPrefLibTrapUpdateFromRadioNV);
    00474
    00475
    00476 /** Called by the Network prefs. panel when it receives the
    00477  * sysAppLaunchCmdSyncNotify action code from HotSync or IR stack.
    00478  * This happens whenever the network preferences database NetworkDB
    00479  * or the Network panel are HotSynced or IR-beamed to the device.
    00480  *
    00481  * NOTE: this may be called from a background task with a rather
    00482  * small runtime stack (as in the case of HotSync).
    00483  */
    00484 extern Err
    00485 NetPrefHandleHotSyncNotify (UInt16 refNum,
    00486                             struct NetPrefContextTypeTag* cxtP,
    00487                             UInt16 cmd, void* cmdPBP)
    00488     NETPREF_LIB_TRAP (netPrefLibTrapHandleHotSyncNotify);
    00489
    00490
    00491 /***********************************************************************
    00492  *
    00493  * FUNCTION:     NetPrefRecLongFieldGet
    00494  *
    00495  * DESCRIPTION:  Get a UInt32 field value from a record
    00496  *
    00497  * PARAMETERS:
    00498  *    refNum          IN  NetPrefLib reference number (from SysLibFind
    00499  *                         or SysLibLoad)
    00500  *    cxtP            IN  Open NetPref library context as returned by
    00501  *                         a successful call to NetPrefLibOpen
    00502  *    recP -
    00503  *    recFieldID    -
    00504  *    resultP   - value, set to zero if not available
    00505  *    viewFlagsP - OUT field's view flags -- OPTIONAL - set to
    00506  *                                NULL to ignore
    00507  *
    00508  *  CALLED BY:
    00509  *
    00510  * RETURNED:     true if available (set), false if not
    00511  ***********************************************************************/
    00512 extern Boolean
    00513 NetPrefRecLongFieldGet (UInt16 refNum,
    00514                         struct NetPrefContextTypeTag* cxtP,
    00515                         struct NetPrefRecordTypeTag* recP,
    00516                         NetPrefRecFieldEnum recFieldID,
    00517                         UInt32* resultP,
    00518                         NetPrefRecFieldViewType* viewFlagsP)
    00519     NETPREF_LIB_TRAP (netPrefLibTrapRecLongFieldGet);
    00520
    00521
    00522 /***********************************************************************
    00523  *
    00524  * FUNCTION:     NetPrefRecShortFieldGet
    00525  *
    00526  * DESCRIPTION:  Get a UInt16 field value from a record
    00527  *
    00528  * PARAMETERS:
    00529  *    refNum          IN  NetPrefLib reference number (from SysLibFind
    00530  *                         or SysLibLoad)
    00531  *    cxtP            IN  Open NetPref library context as returned by
    00532  *                         a successful call to NetPrefLibOpen
    00533  *    recP -
    00534  *    recFieldID    -
    00535  *    resultP   - value, set to zero if not available
    00536  *    viewFlagsP - [OPTIONAL] view flags
    00537  *
    00538  *  CALLED BY:
    00539  *
    00540  * RETURNED:     true if available (set), false if not
    00541  ***********************************************************************/
    00542 extern Boolean
    00543 NetPrefRecShortFieldGet (UInt16 refNum,
    00544                         struct NetPrefContextTypeTag* cxtP,
    00545                         struct NetPrefRecordTypeTag* recP,
    00546                         NetPrefRecFieldEnum recFieldID,
    00547                         UInt16* resultP,
    00548                         NetPrefRecFieldViewType* viewFlagsP)
    00549     NETPREF_LIB_TRAP (netPrefLibTrapRecShortFieldGet);
    00550
    00551
    00552 /***********************************************************************
    00553  *
    00554  * FUNCTION:     NetPrefRecByteFieldGet
    00555  *
    00556  * DESCRIPTION:  Get a UInt8 field value from a record
    00557  *
    00558  * PARAMETERS:
    00559  *    refNum          IN  NetPrefLib reference number (from SysLibFind
    00560  *                         or SysLibLoad)
    00561  *    cxtP            IN  Open NetPref library context as returned by
    00562  *                         a successful call to NetPrefLibOpen
    00563  *    recP -
    00564  *    recFieldID    -
    00565  *    resultP   - value, set to zero if not available
    00566  *
    00567  *  CALLED BY:
    00568  *
    00569  * RETURNED:     true if available (set), false if not
    00570  ***********************************************************************/
    00571 extern Boolean
    00572 NetPrefRecByteFieldGet (UInt16 refNum,
    00573                         struct NetPrefContextTypeTag* cxtP,
    00574                         struct NetPrefRecordTypeTag* recP,
    00575                         NetPrefRecFieldEnum recFieldID,
    00576                         UInt8* resultP,
    00577                         NetPrefRecFieldViewType* viewFlagsP)
    00578     NETPREF_LIB_TRAP (netPrefLibTrapRecByteFieldGet);
    00579
    00580
    00581 /**************************************************************
    00582  *  Function:     NetPrefRecFieldViewGet
    00583  *
    00584  *  Summary:
    00585  *    Returns field view flags for a given field of the given record.
    00586  *
    00587  *  Parameters:
    00588  *    refNum          IN  NetPrefLib reference number (from SysLibFind
    00589  *                         or SysLibLoad)
    00590  *    cxtP            IN  Open NetPref library context as returned by
    00591  *                         a successful call to NetPrefLibOpen
    00592  *    recP            IN  NetPref record object
    00593  *    recFieldID      IN  NetPref record field ID
    00594  *
    00595  *  Returns:
    00596  *    NetPrefRecFieldViewType
    00597  ****************************************************************/
    00598 extern NetPrefRecFieldViewType
    00599 NetPrefRecFieldViewGet (UInt16 refNum,
    00600                          struct NetPrefContextTypeTag* cxtP,
    00601                          struct NetPrefRecordTypeTag* recP,
    00602                          NetPrefRecFieldEnum recFieldID)
    00603     NETPREF_LIB_TRAP (netPrefLibTrapRecFieldViewGet);
    00604
    00605
    00606 /***********************************************************************
    00607  *
    00608  * FUNCTION:     NetPrefRecLongFieldSetAsFlags
    00609  *
    00610  * DESCRIPTION:  Set a 32-bit field data value as flags. The clear
    00611  *               operation is performed before the set operation.  To
    00612  *               skip either operation, set the corresponding parameter to 0.
    00613  *
    00614  * PARAMETERS:
    00615  *    refNum          IN  NetPrefLib reference number (from SysLibFind
    00616  *                         or SysLibLoad)
    00617  *    cxtP            IN  Open NetPref library context as returned by
    00618  *                         a successful call to NetPrefLibOpen
    00619  *    recP -
    00620  *    recFieldID    -
    00621  *    resultP   - value, set to zero if not available
    00622  *    flagsToClear    IN flags to clear, or 0 to skip
    00623  *    flagsToSet      IN flags to set, or 0 to skip
    00624  *
    00625  *  CALLED BY:
    00626  *
    00627  * RETURNED:     0 on success
    00628  ***********************************************************************/
    00629 extern Err
    00630 NetPrefRecLongFieldSetAsFlags (UInt16 refNum,
    00631                                struct NetPrefContextTypeTag* cxtP,
    00632                                struct NetPrefRecordTypeTag* recP,
    00633                                NetPrefRecFieldEnum recFieldID,
    00634                                UInt32 flagsToClear, UInt32 flagsToSet)
    00635     NETPREF_LIB_TRAP (netPrefLibTrapRecLongFieldSetAsFlags);
    00636
    00637
    00638 /***************************************************************
    00639  *  Function:     NetPrefRecFieldSetFromBinHandle
    00640  *
    00641  *  Summary:      Set a record object binary field from a PalmOS
    00642  *                memory handle.
    00643  *
    00644  *  Parameters:
    00645  *    refNum          IN  NetPrefLib reference number (from SysLibFind
    00646  *                         or SysLibLoad)
    00647  *    cxtP            IN  Open NetPref library context as returned by
    00648  *                         a successful call to NetPrefLibOpen
    00649  *    recP            IN/OUT  record object
    00650  *    recFieldID      IN      field ID -- NetPrefRecFieldEnum
    00651  *    dataH           IN      data handle
    00652  *
    00653  *  Returns:
    00654  *    0 on success
    00655  ****************************************************************/
    00656 extern Err
    00657 NetPrefRecFieldSetFromBinHandle (UInt16 refNum,
    00658                                 struct NetPrefContextTypeTag* cxtP,
    00659                                 struct NetPrefRecordTypeTag* recP,
    00660                                 NetPrefRecFieldEnum recFieldID,
    00661                                 MemHandle dataH)
    00662     NETPREF_LIB_TRAP (netPrefLibTrapRecFieldSetFromBinHandle);
    00663
    00664
    00665 /***************************************************************
    00666  *  Function:     NetPrefRecFieldSetFromStrHandle
    00667  *
    00668  *  Summary:      Set a record object string field from a PalmOS memory handle.
    00669  *
    00670  *  Parameters:
    00671  *    refNum          IN  NetPrefLib reference number (from SysLibFind
    00672  *                         or SysLibLoad)
    00673  *    cxtP            IN  Open NetPref library context as returned by
    00674  *                         a successful call to NetPrefLibOpen
    00675  *    recP            IN/OUT  record object
    00676  *    recFieldID      IN      field ID -- NetPrefRecFieldEnum
    00677  *    dataH           IN      string handle -- zero-terminated; may be NULL
    00678  *
    00679  *  Returns:
    00680  *    0 on success
    00681  ****************************************************************/
    00682 extern Err
    00683 NetPrefRecFieldSetFromStrHandle (UInt16 refNum,
    00684                                 struct NetPrefContextTypeTag* cxtP,
    00685                                 struct NetPrefRecordTypeTag* recP,
    00686                                 NetPrefRecFieldEnum recFieldID,
    00687                                 MemHandle dataH)
    00688     NETPREF_LIB_TRAP (netPrefLibTrapRecFieldSetFromStrHandle);
    00689
    00690
    00691 /***************************************************************
    00692  *  Function:     NetPrefRecFieldSetFromStrPtr
    00693  *
    00694  *  Summary:      Set a record object string field from a PalmOS memory handle.
    00695  *
    00696  *  Parameters:
    00697  *    refNum          IN  NetPrefLib reference number (from SysLibFind
    00698  *                         or SysLibLoad)
    00699  *    cxtP            IN  Open NetPref library context as returned by
    00700  *                         a successful call to NetPrefLibOpen
    00701  *    recP            IN/OUT  record object
    00702  *    recFieldID      IN      field ID -- NetPrefRecFieldEnum
    00703  *    strP            IN      string pointer -- zero-terminated; may be NULL
    00704  *
    00705  *  Returns:
    00706  *    0 on success
    00707  ****************************************************************/
    00708 extern Err
    00709 NetPrefRecFieldSetFromStrPtr (UInt16 refNum,
    00710                               struct NetPrefContextTypeTag* cxtP,
    00711                               struct NetPrefRecordTypeTag* recP,
    00712                               NetPrefRecFieldEnum recFieldID,
    00713                               char* strP)
    00714     NETPREF_LIB_TRAP (netPrefLibTrapRecFieldSetFromStrPtr);
    00715
    00716
    00717
    00718 /***************************************************************
    00719  *  Function:     NetPrefRecConnectionInfoGet
    00720  *
    00721  *  Summary:      Get the port ID and modem status of the connection
    00722  *                referenced by the record object.
    00723  *
    00724  *  Parameters:
    00725  *    refNum          IN  NetPrefLib reference number (from SysLibFind
    00726  *                         or SysLibLoad)
    00727  *    cxtP            IN  Open NetPref library context as returned by
    00728  *                         a successful call to NetPrefLibOpen
    00729  *    recP            IN  record object
    00730  *
    00731  *  Returns:
    00732  *    true if got information, false if connection is not in the Connection
    00733  *    Manager database
    00734  ****************************************************************/
    00735 extern Boolean
    00736 NetPrefRecConnectionInfoGet (UInt16 refNum,
    00737                             struct NetPrefContextTypeTag* cxtP,
    00738                             struct NetPrefRecordTypeTag* recP,
    00739                             UInt32* portCreatorIDP, Boolean* isModemP)
    00740     NETPREF_LIB_TRAP (netPrefLibTrapRecConnectionInfoGet);
    00741
    00742
    00743 /***************************************************************
    00744  *  Function:     NetPrefRecMediumDerive
    00745  *
    00746  *  Summary:      Determine the record's "medium" (NetPrefSvcMediumEnum).
    00747  *                Determine based on Connection name and/or
    00748  *                the value of the netPrefRecFieldMedium.
    00749  *                The precedence goes to netPrefRecFieldMedium.
    00750  *
    00751  *  Parameters:
    00752  *    refNum          IN  NetPrefLib reference number (from SysLibFind
    00753  *                         or SysLibLoad)
    00754  *    cxtP            IN  Open NetPref library context as returned by
    00755  *                         a successful call to NetPrefLibOpen
    00756  *    recP            IN  record object
    00757  *
    00758  *  Returns:
    00759  *    NetPrefSvcMediumEnum
    00760  ****************************************************************/
    00761 extern NetPrefSvcMediumEnum
    00762 NetPrefRecMediumDerive (UInt16 refNum,
    00763                          struct NetPrefContextTypeTag* cxtP,
    00764                          struct NetPrefRecordTypeTag* recP,
    00765                          UInt32 defWirelessDriverID)
    00766     NETPREF_LIB_TRAP (netPrefLibTrapRecMediumDerive);
    00767
    00768
    00769 /***********************************************************************
    00770  *
    00771  * FUNCTION:    NetPrefRecIPAddrFieldSet
    00772  *
    00773  * DESCRIPTION: Set the value of an IP address field in the record object.
    00774  *              If the IP address is 0, saves a value of 0 length to
    00775  *              optimize memory access performance
    00776  *
    00777  * PARAMETERS:
    00778  *    refNum          IN  NetPrefLib reference number (from SysLibFind
    00779  *                         or SysLibLoad)
    00780  *    cxtP            IN  Open NetPref library context as returned by
    00781  *                         a successful call to NetPrefLibOpen
    00782  *    recP  - record object
    00783  *    recFieldID - record object field ID to set
    00784  *    ipAddr - IP address
    00785  *
    00786  * RETURNED:    0 on success.
    00787  ***********************************************************************/
    00788 extern Err
    00789 NetPrefRecIPAddrFieldSet (UInt16 refNum,
    00790                           struct NetPrefContextTypeTag* cxtP,
    00791                           struct NetPrefRecordTypeTag* recP,
    00792                           NetPrefRecFieldEnum recFieldID, UInt32 ipAddr)
    00793     NETPREF_LIB_TRAP (netPrefLibTrapRecIPAddrFieldSet);
    00794
    00795
    00796 /***********************************************************************
    00797  *
    00798  * FUNCTION:      NetPrefUtilZStringListSizeGet
    00799  *
    00800  * DESCRIPTION:   Return the length of a zero-terminated string list.  A
    00801  *                zero-terminated string list consists of zero-terminated
    00802  *                strings and ends with an empty string.  The size includes.
    00803  *                all of the zero-terminators, including the list terminator.
    00804  *
    00805  * PARAMETERS:
    00806  *    refNum          IN  NetPrefLib reference number (from SysLibFind
    00807  *                         or SysLibLoad)
    00808  *    cxtP            IN  Open NetPref library context as returned by
    00809  *                         a successful call to NetPrefLibOpen
    00810  *    zStrListP - pointer to the zero-terminated sting list
    00811  *
    00812  * RETURNED:
    00813  *    The size of the list, including all of the zero-terminators and
    00814  *    the list terminator.
    00815  *
    00816  * REVISION HISTORY:
    00817  *          Name    Date        Description
    00818  *          ----    ----        -----------
    00819  *          vmk     2/11/02     Created based on Palm's SetPrefStr from
    00820  *                              Network Panel.
    00821  ***********************************************************************/
    00822 extern UInt32
    00823 NetPrefUtilZStringListSizeGet (UInt16 refNum,
    00824                                struct NetPrefContextTypeTag* cxtP,
    00825                                char* zStrListP)
    00826     NETPREF_LIB_TRAP (netPrefLibTrapUtilZStringListSizeGet);
    00827
    00828 #define NetPrefUtilLoginScriptLen(refNum, cxtP, scriptP) \
    00829                 NetPrefUtilZStringListSizeGet ((refNum), (cxtP), \
    00830                                                (scriptP))
    00831
    00832
    00833 /***********************************************************************
    00834  *
    00835  * FUNCTION:     NetPrefRecPhoneStringCompose
    00836  *
    00837  * DESCRIPTION: Compose a phone string from the record object.
    00838  *              contcatenate the dial prefix, disable
    00839  *              call waiting, calling card number, and the phone
    00840  *              number
    00841  *
    00842  * PARAMETERS:
    00843  *    refNum          IN  NetPrefLib reference number (from SysLibFind
    00844  *                         or SysLibLoad)
    00845  *    cxtP            IN  Open NetPref library context as returned by
    00846  *                         a successful call to NetPrefLibOpen
    00847  *    recP            IN  record object
    00848  *    destP           OUT string buffer to hold the complete number
    00849  *                         maxLen     IN  the allocated length of destP -1
    00850  *
    00851  * RETURNED:    nothing
    00852  ***********************************************************************/
    00853 extern void
    00854 NetPrefRecPhoneStringCompose (UInt16 refNum,
    00855                               struct NetPrefContextTypeTag* cxtP,
    00856                               struct NetPrefRecordTypeTag* recP,
    00857                               Char* destP, UInt16 maxLen)
    00858     NETPREF_LIB_TRAP (netPrefLibTrapRecPhoneStringCompose);
    00859
    00860
    00861 /***********************************************************************
    00862  *
    00863  * Function:    NetPrefUtilPlatformIDGet
    00864  *
    00865  * Summary:     Determine on which platform we are running -- CDMA or GSM
    00866  *
    00867  * Parameters:
    00868  *    nothing
    00869  *
    00870  * Returns:
    00871  *    refNum          IN  NetPrefLib reference number (from SysLibFind
    00872  *                         or SysLibLoad)
    00873  *    cxtP            IN  Open NetPref library context as returned by
    00874  *                         a successful call to NetPrefLibOpen -- MAY BE NULL!
    00875  *    NetPrefPlatformEnum or netPrefPlatformUnknown if could not
    00876  *    identify
    00877  ***********************************************************************/
    00878 extern NetPrefPlatformEnum
    00879 NetPrefUtilPlatformIDGet (UInt16 refNum, struct NetPrefContextTypeTag* cxtP)
    00880     NETPREF_LIB_TRAP (netPrefLibTrapUtilPlatformIDGet);
    00881
    00882
    00883 /***********************************************************************
    00884  *
    00885  * Function:    NetPrefUtilDefWirelessDriverIDGet
    00886  *
    00887  * Summary:     Get the default wireless driver ID for the given platform
    00888  *
    00889  * Parameters:
    00890  *    refNum          IN  NetPrefLib reference number (from SysLibFind
    00891  *                         or SysLibLoad)
    00892  *    cxtP            IN  Open NetPref library context as returned by
    00893  *                         a successful call to NetPrefLibOpen -- MAY BE NULL!
    00894  *    platform        IN    platform ID (from NetPrefUtilPlatformIDGet())
    00895  *
    00896  * Returns:
    00897  *    Wireless driver ID (creator) or 0 if platform is not wireless
    00898  ***********************************************************************/
    00899 extern UInt32
    00900 NetPrefUtilDefWirelessDriverIDGet (UInt16 refNum,
    00901                                    struct NetPrefContextTypeTag* cxtP,
    00902                                    NetPrefPlatformEnum platform)
    00903     NETPREF_LIB_TRAP (netPrefLibTrapUtilDefWirelessDriverIDGet);
    00904
    00905
    00906 #ifdef __cplusplus
    00907 }
    00908 #endif
    00909
    00910
    00911 #endif // _NET_PREF_LIBRARY_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