(Online version only)
|
API Guide Home (Online version only) |
|
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 |