API Guide Home
(Online version only)

Header Files » Incs » 68k » libraries » netpref

NetPrefLibrary.h File Reference

Detailed Description

This is the main header file for the NetPref Library.

Version:
1.0
Date:
06/24/2002
USAGE MODEL: The model for using the NetPref library is that you "link" it in when needed and "unlink" it as you're done -- i.e. we don't leave it permanently installed as we do with some other libraries. This helps us avoid some unpleasant HotSync issues (such as trying to install over a protected database). For examples of linking and unlinking, grep for calls to NetPrefUtilNetPrefLibLink and NetPrefUtilNetPrefLibUnlink in NetworkPanel.c (Network panel src folder). NetPrefUtilNetPrefLibLink and NetPrefUtilNetPrefLibUnlink are defined in Viewer\Libraries\NetPref\Public\Util\NetPrefUtils.c/h -- you may include the .c file with your code, or just copy and paste out of those functions.

Definition in file NetPrefLibrary.h.

Include dependency graph for NetPrefLibrary.h:

Go to the source code of this file.

Defines

Functions

Define Documentation

#define NETPREF_LIB_TRAP ( trapNum   )     SYS_TRAP(trapNum)

Definition at line 55 of file NetPrefLibrary.h.

#define NetPrefUtilLoginScriptLen ( refNum,
cxtP,
scriptP   ) 

Value:

NetPrefUtilZStringListSizeGet ((refNum), (cxtP), \
                                               (scriptP))

Definition at line 828 of file NetPrefLibrary.h.

Function Documentation

Err NetPrefDefaultTargetGet ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
NetPrefSvcTargetEnum  svcTarget,
UInt32 *  recIDP 
)

Get the default service ID for the given target

Err NetPrefDefaultTargetSet ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
NetPrefSvcTargetEnum  svcTarget,
UInt32  recID 
)

Set the given service as the default service for the given target type; Set recID to 0 (zero) to clear the default for that target type. (WAP, Internet, all, etc.)

Err NetPrefHandleHotSyncNotify ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
UInt16  cmd,
void *  cmdPBP 
)

Called by the Network prefs. panel when it receives the sysAppLaunchCmdSyncNotify action code from HotSync or IR stack. This happens whenever the network preferences database NetworkDB or the Network panel are HotSynced or IR-beamed to the device.

NOTE: this may be called from a background task with a rather small runtime stack (as in the case of HotSync).

Err NetPrefLibClose ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP 
)

Standard library close routine.

Parameters:
refnum,: IN: Library reference number
Return values:
Err Library error code

Err NetPrefLibOpen ( UInt16  refNum,
struct NetPrefContextTypeTag **  cxtPP 
)

Standard library open routine.

Parameters:
refnum,: IN: Library reference number
Return values:
Err Library error code

Err NetPrefLibSleep ( UInt16  refNum  ) 

Standard library sleep routine.

Parameters:
refnum,: IN: Library reference number
Return values:
Err Library error code

Err NetPrefLibVersionGet ( UInt16  refNum,
UInt32 *  majorVerP,
UInt32 *  minorVerP,
UInt32 *  bugFixVerP 
)

Get Library API Version number.

Parameters:
refnum,: IN: Library reference number
majorVerP,: OUT: Major version number
minorVerP,: OUT: Minor version number
bugFixVerP,: OUT: Bug fix version number
Return values:
Err NetPref Library error code

Err NetPrefLibWake ( UInt16  refNum  ) 

Standard library wake routine.

Parameters:
refnum,: IN: Library reference number
Return values:
Err Library error code

Err NetPrefRecBindingErrorGet ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP 
)

Call this to check if there was an error from application of a binding (such as CCSM) to the record.

Boolean NetPrefRecByteFieldGet ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP,
NetPrefRecFieldEnum  recFieldID,
UInt8 *  resultP,
NetPrefRecFieldViewType *  viewFlagsP 
)

Boolean NetPrefRecConnectionInfoGet ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP,
UInt32 *  portCreatorIDP,
Boolean *  isModemP 
)

Err NetPrefRecCountGet ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
UInt16 *  countP 
)

Retrieve the count of records in the NetPref database

Err NetPrefRecDelete ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
UInt32  recID 
)

Delete the given record from the database; if the record is bound to another, such as that stored in non-volatile memory of the radio module, will delete the primary record as well. If the client has a memory object representing the record being deleted, the client is still responsible for releasing it via NetPrefRecRelease().

void NetPrefRecDirtyFlagsReset ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP 
)

Reset all of the record's "dirty" flags. NOTE: NetPrefRecSave will not save a record that is not marked as "dirty"

Err NetPrefRecFieldAddToSet ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP,
NetPrefRecFieldEnum  recFieldID,
NetPrefRecFieldViewType *  initialViewFlagsP 
)

Add a field to the Field-set of a given record and, optionally, set its view flags (set initialViewFlagsP to NULL to leave the field's view flags alone).

NOTE: If the field was already part of the record's field-set, the field's data will be preserved. However, the field's view flags will be overwritten with those supplied via initialViewFlagsP if initialViewFlagsP is not NULL.

Err NetPrefRecFieldAttrsGet ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP,
NetPrefRecFieldEnum  recFieldID,
NetPrefRecFieldAttrType *  fieldAttrsP 
)

Get the attributes of a field

Err NetPrefRecFieldGet ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP,
NetPrefRecFieldEnum  recFieldID,
void **  fieldValuePP,
UInt32 *  fieldLenP,
NetPrefRecFieldViewType *  viewFlagsP 
)

Get a pointer to a given record field; upon successful return, the value of the field is to be interpreted as follows:

NULL -- field value is not assigned non-NULL -- field value has been assigned, the value must be treated as read-only! Field view depends on the Medium and Binding of the record

Err NetPrefRecFieldSet ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP,
NetPrefRecFieldEnum  recFieldID,
void *  fieldValueP,
UInt32  fieldLen 
)

NetPrefRecFieldSet: Set the value of the field. The library will duplicate the value passed in fieldValueP. Set fieldValueP to NULL to delete the field's data. NOTE: setting a field invalidates any cached pointer that you may already have to the field's value.

NOTES: 1) Field must be in record's field-set before you can set its data or view flags.

2) String field values MUST be zero-terminated and the fieldLen MUST include the zero-terminator.

3) If a change results, the record object will be marked as dirty

Err NetPrefRecFieldSetDefine ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP,
NetPrefRecFieldEnum *  recFieldIDArrayP,
UInt16  newNumFields,
NetPrefRecFieldViewType *  initialViewFlagsP,
NetPrefFieldSetDefineOptionsType  options 
)

Define the field set associated with the record; fields that are not in the new field will be removed from the record object. For fields in the new field set, existing data will be left alone.

You may pass a pointer to new NetPrefRecFieldViewType in initialViewFlagsP to set those view flags in all the fields in the new field set (or pass NULL to ignore this parameter and leave field view flags at their old values).

To remove all fields from the field set, set newNumFields to 0 and recFieldIDArrayP to NULL;

Err NetPrefRecFieldSetDefineStd ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP,
NetPrefSvcMediumEnum  svcMedium,
NetPrefRecFieldViewType *  initialViewFlagsP,
NetPrefFieldSetDefineOptionsType  options 
)

Define a "standard" field set based on Service Medium value -- basically, this is what the New Network Preference panel uses when it creates new services.

You may pass a pointer to new NetPrefRecFieldViewType in initialViewFlagsP to set the view flags of all the fields in the new field set (or pass NULL for default flags).

Err NetPrefRecFieldSetFromBinHandle ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP,
NetPrefRecFieldEnum  recFieldID,
MemHandle  dataH 
)

Err NetPrefRecFieldSetFromStrHandle ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP,
NetPrefRecFieldEnum  recFieldID,
MemHandle  dataH 
)

Err NetPrefRecFieldSetFromStrPtr ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP,
NetPrefRecFieldEnum  recFieldID,
char *  strP 
)

Err NetPrefRecFieldSetGet ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP,
NetPrefRecFieldEnum *  recFieldIDArrayP,
UInt16  numEntriesAvailable,
UInt16 *  numFieldsInSetP 
)

Get the current field set of the record object. The array recFieldIDArrayP MUST have enough entries (numEntriesAvailable) to receive the field ID's of all fields in the field set. The actual count of fields in the field set is returned in *numFieldsInSetP. To simply get the count of fields in the field set, without returning the actual field ID's, set numEntriesAvailable to 0 and recFieldIDArrayP to NULL;

NetPrefRecFieldViewType NetPrefRecFieldViewGet ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP,
NetPrefRecFieldEnum  recFieldID 
)

Err NetPrefRecFieldViewSet ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP,
NetPrefRecFieldEnum  recFieldID,
NetPrefRecFieldViewType  flagsToClear,
NetPrefRecFieldViewType  flagsToSet 
)

Set the view flags of the field. If a change results, the record object will be marked as dirty.

NOTES: 1) Field must be in record's field-set before you can set its data or view flags.

2) If a change results, the record object will be marked as dirty

Err NetPrefRecIDGet ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP,
UInt32 *  recIDP 
)

Get the unique record ID of the record's entry in the database.

WARNING: It is an error to call NetPrefRecIDGet on records that have not been attached to the database -- see NetPrefRecIsAttached().

Err NetPrefRecIDGetByIndex ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
UInt16  recIndex,
UInt32 *  recIDP 
)

Get record ID given the 0-based record index, which must be in range of 0..NetPrefRecCountGet()-1. The record's index may change following the NetPrefRecSave opeation.

Err NetPrefRecIndexGet ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP,
UInt16 *  recIndexP 
)

Get the 0-based index of the record's entry in the database. The record's index may change following the NetPrefRecSave opeation.

WARNING: It is an error to call NetPrefRecIndexGet on records that have not been attached to the database -- see NetPrefRecIsAttached().

Err NetPrefRecIndexGetByID ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
UInt32  recID,
UInt16 *  recIndexP 
)

Get record index given the unique record ID, which must be non-zero. The record's index may change following the NetPrefRecSave opeation.

Err NetPrefRecIPAddrFieldSet ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP,
NetPrefRecFieldEnum  recFieldID,
UInt32  ipAddr 
)

Boolean NetPrefRecIsAttached ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP 
)

Check if this record object is "attached" to the database. A record that has been created via NetPrefRecObjAlloc and never saved is not "attached" to the database.

Err NetPrefRecIsDirty ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP,
UInt8 *  isDirtyP 
)

Check if the record is dirty (has been modified by the client)

Err NetPrefRecLoad ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
UInt32  recID,
struct NetPrefRecordTypeTag **  recPP 
)

Load an existing record into memory; the caller is responsible for calling NetPrefRecRelease() to dispose of the temporary resources associated with the loaded record.

Boolean NetPrefRecLongFieldGet ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP,
NetPrefRecFieldEnum  recFieldID,
UInt32 *  resultP,
NetPrefRecFieldViewType *  viewFlagsP 
)

Err NetPrefRecLongFieldSetAsFlags ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP,
NetPrefRecFieldEnum  recFieldID,
UInt32  flagsToClear,
UInt32  flagsToSet 
)

void NetPrefRecMarkDirty ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP 
)

Mark a record as "dirty" so it would be saved by NetPrefRecSave.

NetPrefSvcMediumEnum NetPrefRecMediumDerive ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP,
UInt32  defWirelessDriverID 
)

Err NetPrefRecNew ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
UInt32  dupRecID,
struct NetPrefRecordTypeTag **  recPP 
)

Create a new record object. Pass a non-zero dupRecID to duplicate an existing record. The caller is responsible for calling NetPrefRecRelease() to dispose of the temporary resources associated with the loaded record

Err NetPrefRecObjAlloc ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag **  recPP 
)

Allocate a "blank slate" record object. This record will not be "attached" to the database until saved via NetPrefRecSave. Intended for use with NetPrefRecObjCopy, and by internal code.

Err NetPrefRecObjCopy ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  srcRecP,
struct NetPrefRecordTypeTag *  dstRecP 
)

Copy the contents of the source record object to the destination record object. This is useful for implementing revert functionality.

void NetPrefRecPhoneStringCompose ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP,
Char *  destP,
UInt16  maxLen 
)

void NetPrefRecReadOnlyOverrideEnd ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP 
)

void NetPrefRecReadOnlyOverrideStart ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP 
)

NetPrefRecReadOnlyOverrideStart/End: Increment/decrement the record object's readOnlyOverrideCount variable. The two function calls must be balanced -- i.e., ...End must be called exactly as many times as ...Start regardless of other events, such as errors. If greater than zero, NetPrefRecFieldSet will allow the field to be set regardless of the record's read-only status. This permits internal record "loaders" to initialize record fields regardless of the read-only status of the fields being loaded.

Err NetPrefRecRelease ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag **  recPP 
)

Dispose of the temporary resources associated with a record that was created or loaded via NetPrefRecNew or NetPrefRecLoad. It's the library client's (application's) responsibility to call this function to free up the memory. Resets *recPP to NULL.

Err NetPrefRecSave ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP 
)

Save the record to the database, moving it to a new sorted position if necessary. For existing records, if any fields have been changed, you must call NetPrefRecSave in order to get an accurate record index.

Boolean NetPrefRecShortFieldGet ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
struct NetPrefRecordTypeTag *  recP,
NetPrefRecFieldEnum  recFieldID,
UInt16 *  resultP,
NetPrefRecFieldViewType *  viewFlagsP 
)

Err NetPrefUpdateFromRadioNV ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
Boolean  force 
)

Update the NetPref database from the Non-Volatile storage of the radio, if any. This should be called by the IOTA application after provisioning, as well as when the wireless mode is turned on. This function is optimized to quickly determine if synchronization is necessary, and skip it if not. Set "force" to true to skip optimization and force synchronization.

UInt32 NetPrefUtilDefWirelessDriverIDGet ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
NetPrefPlatformEnum  platform 
)

NetPrefPlatformEnum NetPrefUtilPlatformIDGet ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP 
)

UInt32 NetPrefUtilZStringListSizeGet ( UInt16  refNum,
struct NetPrefContextTypeTag *  cxtP,
char *  zStrListP 
)

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