/******************************************************************************
* Copyright (c) 2004 palmOne, Inc. or its subsidiaries.
* All rights reserved.
*****************************************************************************/
/**
* @ingroup NETPREF
*/
/**
* @file NetPrefLibrary.h
* @version 1.0
* @date 06/24/2002
*
* @brief This is the main header file for the NetPref Library.
*
* 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.
*
*/
/*
* @author Vitaly Kruglikov
*
* History:
* 12-Dec-2001 vmk Created by Vitaly Kruglikov
* 24-Jun-2002 vmk Removed inclusion of private header file
* OSServices.h.
*
*/
#ifndef _NET_PREF_LIBRARY_H_
#define _NET_PREF_LIBRARY_H_
#include
#include
#include
#include <68K/Libraries/NetPref/NetPrefLibTypes.h>
#ifdef BUILDING_NET_PREF_LIB_DISPATCH_TABLE
#define NETPREF_LIB_TRAP(trapNum)
#else
#define NETPREF_LIB_TRAP(trapNum) SYS_TRAP(trapNum)
#endif
#ifdef __cplusplus
extern "C" {
#endif
/** Standard library open routine.
*
* @param refnum: IN: Library reference number
* @retval Err Library error code
*/
extern Err NetPrefLibOpen (UInt16 refNum, struct NetPrefContextTypeTag** cxtPP)
NETPREF_LIB_TRAP (sysLibTrapOpen);
/** Standard library close routine.
*
* @param refnum: IN: Library reference number
* @retval Err Library error code
*/
extern Err NetPrefLibClose (UInt16 refNum, struct NetPrefContextTypeTag* cxtP)
NETPREF_LIB_TRAP (sysLibTrapClose);
/** Standard library sleep routine.
*
* @param refnum: IN: Library reference number
* @retval Err Library error code
*/
extern Err NetPrefLibSleep (UInt16 refNum)
NETPREF_LIB_TRAP (sysLibTrapSleep);
/** Standard library wake routine.
*
* @param refnum: IN: Library reference number
* @retval Err Library error code
*/
extern Err NetPrefLibWake (UInt16 refNum)
NETPREF_LIB_TRAP (sysLibTrapWake);
/** Get Library API Version number.
*
* @param refnum: IN: Library reference number
* @param majorVerP: OUT: Major version number
* @param minorVerP: OUT: Minor version number
* @param bugFixVerP: OUT: Bug fix version number
* @retval Err NetPref Library error code
*/
extern Err
NetPrefLibVersionGet (UInt16 refNum, UInt32* majorVerP, UInt32* minorVerP,
UInt32* bugFixVerP)
NETPREF_LIB_TRAP (netPrefLibTrapVersionGet);
// Retrieve the count of records in the NetPref database
extern Err
NetPrefRecCountGet (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
UInt16* countP)
NETPREF_LIB_TRAP (netPrefLibTrapRecCountGet);
// 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.
extern Err
NetPrefRecIDGetByIndex (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
UInt16 recIndex, UInt32* recIDP)
NETPREF_LIB_TRAP (netPrefLibTrapRecIDGetByIndex);
// Get record index given the unique record ID, which must be
// non-zero.
// The record's index may change following the NetPrefRecSave opeation.
extern Err
NetPrefRecIndexGetByID (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
UInt32 recID, UInt16* recIndexP)
NETPREF_LIB_TRAP (netPrefLibTrapRecIndexGetByID);
// 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
extern Err
NetPrefRecNew (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
UInt32 dupRecID, struct NetPrefRecordTypeTag** recPP)
NETPREF_LIB_TRAP (netPrefLibTrapRecNew);
// Load an existing record into memory; the caller is responsible for
// calling NetPrefRecRelease() to dispose of the temporary resources
// associated with the loaded record.
extern Err
NetPrefRecLoad (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
UInt32 recID, struct NetPrefRecordTypeTag** recPP)
NETPREF_LIB_TRAP (netPrefLibTrapRecLoad);
// Call this to check if there was an error from application of a binding
// (such as CCSM) to the record.
extern Err
NetPrefRecBindingErrorGet (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP)
NETPREF_LIB_TRAP (netPrefLibTrapRecBindingErrorGet);
// 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.
extern Err
NetPrefRecRelease (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag** recPP)
NETPREF_LIB_TRAP (netPrefLibTrapRecRelease);
// 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.
extern Err
NetPrefRecSave (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP)
NETPREF_LIB_TRAP (netPrefLibTrapRecSave);
// 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.
extern Boolean
NetPrefRecIsAttached (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP)
NETPREF_LIB_TRAP (netPrefLibTrapRecIsAttached);
// 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.
extern Err
NetPrefRecObjAlloc (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag** recPP)
NETPREF_LIB_TRAP (netPrefLibTrapRecObjAlloc);
// Copy the contents of the source record object to the destination
// record object. This is useful for implementing revert functionality.
extern Err
NetPrefRecObjCopy (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* srcRecP,
struct NetPrefRecordTypeTag* dstRecP)
NETPREF_LIB_TRAP (netPrefLibTrapRecObjCopy);
// 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.
//
extern Err
NetPrefRecIDGet (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP, UInt32* recIDP)
NETPREF_LIB_TRAP (netPrefLibTrapRecIDGet);
// 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.
extern Err
NetPrefRecIndexGet (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP, UInt16* recIndexP)
NETPREF_LIB_TRAP (netPrefLibTrapRecIndexGet);
// 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().
//
extern Err
NetPrefRecDelete (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
UInt32 recID)
NETPREF_LIB_TRAP (netPrefLibTrapRecDelete);
// 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
//
extern Err
NetPrefRecFieldGet (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP,
NetPrefRecFieldEnum recFieldID, void** fieldValuePP,
UInt32* fieldLenP, NetPrefRecFieldViewType* viewFlagsP)
NETPREF_LIB_TRAP (netPrefLibTrapRecFieldGet);
// Get the attributes of a field
extern Err
NetPrefRecFieldAttrsGet (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP,
NetPrefRecFieldEnum recFieldID,
NetPrefRecFieldAttrType* fieldAttrsP)
NETPREF_LIB_TRAP (netPrefLibTrapRecFieldAttrsGet);
// 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
//
extern Err
NetPrefRecFieldSet (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP,
NetPrefRecFieldEnum recFieldID, void* fieldValueP,
UInt32 fieldLen)
NETPREF_LIB_TRAP (netPrefLibTrapRecFieldSet);
// 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
//
extern Err
NetPrefRecFieldViewSet (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP,
NetPrefRecFieldEnum recFieldID,
NetPrefRecFieldViewType flagsToClear,
NetPrefRecFieldViewType flagsToSet)
NETPREF_LIB_TRAP (netPrefLibTrapRecFieldViewSet);
// 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 initilize record
// fields regardless of the read-only status of the fields being loaded.
extern void
NetPrefRecReadOnlyOverrideStart (UInt16 refNum,
struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP)
NETPREF_LIB_TRAP (netPrefLibTrapRecReadOnlyOverrideStart);
extern void
NetPrefRecReadOnlyOverrideEnd (UInt16 refNum,
struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP)
NETPREF_LIB_TRAP (netPrefLibTrapRecReadOnlyOverrideEnd);
// 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;
//
extern Err
NetPrefRecFieldSetDefine (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP,
NetPrefRecFieldEnum* recFieldIDArrayP,
UInt16 newNumFields,
NetPrefRecFieldViewType* initialViewFlagsP,
NetPrefFieldSetDefineOptionsType options)
NETPREF_LIB_TRAP (netPrefLibTrapRecFieldSetDefine);
// 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.
//
extern Err
NetPrefRecFieldAddToSet (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP,
NetPrefRecFieldEnum recFieldID,
NetPrefRecFieldViewType* initialViewFlagsP)
NETPREF_LIB_TRAP (netPrefLibTrapRecFieldAddToSet);
// 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).
extern Err
NetPrefRecFieldSetDefineStd (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP,
NetPrefSvcMediumEnum svcMedium,
NetPrefRecFieldViewType* initialViewFlagsP,
NetPrefFieldSetDefineOptionsType options)
NETPREF_LIB_TRAP (netPrefLibTrapRecFieldSetDefineStd);
// Get the current field set of the record object. The array
// recFieldIDArrayP MUST have enough entries (numEntriesAvailable)
// to recieve 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;
extern Err
NetPrefRecFieldSetGet (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP,
NetPrefRecFieldEnum* recFieldIDArrayP,
UInt16 numEntriesAvailable, UInt16* numFieldsInSetP)
NETPREF_LIB_TRAP (netPrefLibTrapRecFieldSetGet);
// Check if the record is dirty (has been modified by the client)
extern Err
NetPrefRecIsDirty (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP,
UInt8* isDirtyP)
NETPREF_LIB_TRAP (netPrefLibTrapRecIsDirty);
// Reset all of the record's "dirty" flags. NOTE: NetPrefRecSave will not
// save a record that is not marked as "dirty"
extern void
NetPrefRecDirtyFlagsReset (UInt16 refNum,
struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP)
NETPREF_LIB_TRAP (netPrefLibTrapRecDirtyFlagsReset);
// Mark a record as "dirty" so it would be saved by NetPrefRecSave.
extern void
NetPrefRecMarkDirty (UInt16 refNum,
struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP)
NETPREF_LIB_TRAP (netPrefLibTrapRecMarkDirty);
// Get the default service ID for the given target
extern Err
NetPrefDefaultTargetGet (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
NetPrefSvcTargetEnum svcTarget, UInt32* recIDP)
NETPREF_LIB_TRAP (netPrefLibTrapDefaultTargetGet);
// 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.)
extern Err
NetPrefDefaultTargetSet (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
NetPrefSvcTargetEnum svcTarget, UInt32 recID)
NETPREF_LIB_TRAP (netPrefLibTrapDefaultTargetSet);
// 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 synchronizatino is necessary, and skip it if not.
// Set "force" to true to skip optimization and force synchronization.
extern Err
NetPrefUpdateFromRadioNV (UInt16 refNum, struct NetPrefContextTypeTag* cxtP,
Boolean force)
NETPREF_LIB_TRAP (netPrefLibTrapUpdateFromRadioNV);
// 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).
extern Err
NetPrefHandleHotSyncNotify (UInt16 refNum,
struct NetPrefContextTypeTag* cxtP,
UInt16 cmd, void* cmdPBP)
NETPREF_LIB_TRAP (netPrefLibTrapHandleHotSyncNotify);
/***********************************************************************
*
* FUNCTION: NetPrefRecLongFieldGet
*
* DESCRIPTION: Get a UInt32 field value from a record
*
* PARAMETERS:
* refNum IN NetPrefLib reference number (from SysLibFind
* or SysLibLoad)
* cxtP IN Open NetPref library context as returned by
* a successful call to NetPrefLibOpen
* recP -
* recFieldID -
* resultP - value, set to zero if not available
* viewFlagsP - OUT field's view flags -- OPTIONAL - set to
* NULL to ignore
*
* CALLED BY:
*
* RETURNED: true if available (set), false if not
***********************************************************************/
extern Boolean
NetPrefRecLongFieldGet (UInt16 refNum,
struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP,
NetPrefRecFieldEnum recFieldID,
UInt32* resultP,
NetPrefRecFieldViewType* viewFlagsP)
NETPREF_LIB_TRAP (netPrefLibTrapRecLongFieldGet);
/***********************************************************************
*
* FUNCTION: NetPrefRecShortFieldGet
*
* DESCRIPTION: Get a UInt16 field value from a record
*
* PARAMETERS:
* refNum IN NetPrefLib reference number (from SysLibFind
* or SysLibLoad)
* cxtP IN Open NetPref library context as returned by
* a successful call to NetPrefLibOpen
* recP -
* recFieldID -
* resultP - value, set to zero if not available
* viewFlagsP - [OPTIONAL] view flags
*
* CALLED BY:
*
* RETURNED: true if available (set), false if not
***********************************************************************/
extern Boolean
NetPrefRecShortFieldGet (UInt16 refNum,
struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP,
NetPrefRecFieldEnum recFieldID,
UInt16* resultP,
NetPrefRecFieldViewType* viewFlagsP)
NETPREF_LIB_TRAP (netPrefLibTrapRecShortFieldGet);
/***********************************************************************
*
* FUNCTION: NetPrefRecByteFieldGet
*
* DESCRIPTION: Get a UInt8 field value from a record
*
* PARAMETERS:
* refNum IN NetPrefLib reference number (from SysLibFind
* or SysLibLoad)
* cxtP IN Open NetPref library context as returned by
* a successful call to NetPrefLibOpen
* recP -
* recFieldID -
* resultP - value, set to zero if not available
*
* CALLED BY:
*
* RETURNED: true if available (set), false if not
***********************************************************************/
extern Boolean
NetPrefRecByteFieldGet (UInt16 refNum,
struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP,
NetPrefRecFieldEnum recFieldID,
UInt8* resultP,
NetPrefRecFieldViewType* viewFlagsP)
NETPREF_LIB_TRAP (netPrefLibTrapRecByteFieldGet);
/**************************************************************
* Function: NetPrefRecFieldViewGet
*
* Summary:
* Returns field view flags for a given field of the given record.
*
* Parameters:
* refNum IN NetPrefLib reference number (from SysLibFind
* or SysLibLoad)
* cxtP IN Open NetPref library context as returned by
* a successful call to NetPrefLibOpen
* recP IN NetPref record object
* recFieldID IN NetPref record field ID
*
* Returns:
* NetPrefRecFieldViewType
****************************************************************/
extern NetPrefRecFieldViewType
NetPrefRecFieldViewGet (UInt16 refNum,
struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP,
NetPrefRecFieldEnum recFieldID)
NETPREF_LIB_TRAP (netPrefLibTrapRecFieldViewGet);
/***********************************************************************
*
* FUNCTION: NetPrefRecLongFieldSetAsFlags
*
* DESCRIPTION: Set a 32-bit field data value as flags. The clear
* operation is performed before the set operation. To
* skip either operation, set the corresponding parameter to 0.
*
* PARAMETERS:
* refNum IN NetPrefLib reference number (from SysLibFind
* or SysLibLoad)
* cxtP IN Open NetPref library context as returned by
* a successful call to NetPrefLibOpen
* recP -
* recFieldID -
* resultP - value, set to zero if not available
* flagsToClear IN flags to clear, or 0 to skip
* flagsToSet IN flags to set, or 0 to skip
*
* CALLED BY:
*
* RETURNED: 0 on success
***********************************************************************/
extern Err
NetPrefRecLongFieldSetAsFlags (UInt16 refNum,
struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP,
NetPrefRecFieldEnum recFieldID,
UInt32 flagsToClear, UInt32 flagsToSet)
NETPREF_LIB_TRAP (netPrefLibTrapRecLongFieldSetAsFlags);
/***************************************************************
* Function: NetPrefRecFieldSetFromBinHandle
*
* Summary: Set a record object binary field from a PalmOS
* memory handle.
*
* Parameters:
* refNum IN NetPrefLib reference number (from SysLibFind
* or SysLibLoad)
* cxtP IN Open NetPref library context as returned by
* a successful call to NetPrefLibOpen
* recP IN/OUT record object
* recFieldID IN field ID -- NetPrefRecFieldEnum
* dataH IN data handle
*
* Returns:
* 0 on success
****************************************************************/
extern Err
NetPrefRecFieldSetFromBinHandle (UInt16 refNum,
struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP,
NetPrefRecFieldEnum recFieldID,
MemHandle dataH)
NETPREF_LIB_TRAP (netPrefLibTrapRecFieldSetFromBinHandle);
/***************************************************************
* Function: NetPrefRecFieldSetFromStrHandle
*
* Summary: Set a record object string field from a PalmOS memory handle.
*
* Parameters:
* refNum IN NetPrefLib reference number (from SysLibFind
* or SysLibLoad)
* cxtP IN Open NetPref library context as returned by
* a successful call to NetPrefLibOpen
* recP IN/OUT record object
* recFieldID IN field ID -- NetPrefRecFieldEnum
* dataH IN string handle -- zero-terminated; may be NULL
*
* Returns:
* 0 on success
****************************************************************/
extern Err
NetPrefRecFieldSetFromStrHandle (UInt16 refNum,
struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP,
NetPrefRecFieldEnum recFieldID,
MemHandle dataH)
NETPREF_LIB_TRAP (netPrefLibTrapRecFieldSetFromStrHandle);
/***************************************************************
* Function: NetPrefRecFieldSetFromStrPtr
*
* Summary: Set a record object string field from a PalmOS memory handle.
*
* Parameters:
* refNum IN NetPrefLib reference number (from SysLibFind
* or SysLibLoad)
* cxtP IN Open NetPref library context as returned by
* a successful call to NetPrefLibOpen
* recP IN/OUT record object
* recFieldID IN field ID -- NetPrefRecFieldEnum
* strP IN string pointer -- zero-terminated; may be NULL
*
* Returns:
* 0 on success
****************************************************************/
extern Err
NetPrefRecFieldSetFromStrPtr (UInt16 refNum,
struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP,
NetPrefRecFieldEnum recFieldID,
char* strP)
NETPREF_LIB_TRAP (netPrefLibTrapRecFieldSetFromStrPtr);
/***************************************************************
* Function: NetPrefRecConnectionInfoGet
*
* Summary: Get the port ID and modem status of the connection
* referenced by the record object.
*
* Parameters:
* refNum IN NetPrefLib reference number (from SysLibFind
* or SysLibLoad)
* cxtP IN Open NetPref library context as returned by
* a successful call to NetPrefLibOpen
* recP IN record object
*
* Returns:
* true if got information, false if connection is not in the Connection
* Manager database
****************************************************************/
extern Boolean
NetPrefRecConnectionInfoGet (UInt16 refNum,
struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP,
UInt32* portCreatorIDP, Boolean* isModemP)
NETPREF_LIB_TRAP (netPrefLibTrapRecConnectionInfoGet);
/***************************************************************
* Function: NetPrefRecMediumDerive
*
* Summary: Determine the record's "medium" (NetPrefSvcMediumEnum).
* Determine based on Connection name and/or
* the value of the netPrefRecFieldMedium.
* The precedence goes to netPrefRecFieldMedium.
*
* Parameters:
* refNum IN NetPrefLib reference number (from SysLibFind
* or SysLibLoad)
* cxtP IN Open NetPref library context as returned by
* a successful call to NetPrefLibOpen
* recP IN record object
*
* Returns:
* NetPrefSvcMediumEnum
****************************************************************/
extern NetPrefSvcMediumEnum
NetPrefRecMediumDerive (UInt16 refNum,
struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP,
UInt32 defWirelessDriverID)
NETPREF_LIB_TRAP (netPrefLibTrapRecMediumDerive);
/***********************************************************************
*
* FUNCTION: NetPrefRecIPAddrFieldSet
*
* DESCRIPTION: Set the value of an IP address field in the record object.
* If the IP address is 0, saves a value of 0 length to
* optimize memory access performance
*
* PARAMETERS:
* refNum IN NetPrefLib reference number (from SysLibFind
* or SysLibLoad)
* cxtP IN Open NetPref library context as returned by
* a successful call to NetPrefLibOpen
* recP - record object
* recFieldID - record object field ID to set
* ipAddr - IP address
*
* RETURNED: 0 on success.
***********************************************************************/
extern Err
NetPrefRecIPAddrFieldSet (UInt16 refNum,
struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP,
NetPrefRecFieldEnum recFieldID, UInt32 ipAddr)
NETPREF_LIB_TRAP (netPrefLibTrapRecIPAddrFieldSet);
/***********************************************************************
*
* FUNCTION: NetPrefUtilZStringListSizeGet
*
* DESCRIPTION: Return the length of a zero-terminated string list. A
* zero-terminated string list consists of zero-terminated
* strings and ends with an empty string. The size includes.
* all of the zero-terminators, including the list terminator.
*
* PARAMETERS:
* refNum IN NetPrefLib reference number (from SysLibFind
* or SysLibLoad)
* cxtP IN Open NetPref library context as returned by
* a successful call to NetPrefLibOpen
* zStrListP - pointer to the zero-terminated sting list
*
* RETURNED:
* The size of the list, including all of the zero-terminators and
* the list terminator.
*
* REVISION HISTORY:
* Name Date Description
* ---- ---- -----------
* vmk 2/11/02 Created based on Palm's SetPrefStr from
* Network Panel.
***********************************************************************/
extern UInt32
NetPrefUtilZStringListSizeGet (UInt16 refNum,
struct NetPrefContextTypeTag* cxtP,
char* zStrListP)
NETPREF_LIB_TRAP (netPrefLibTrapUtilZStringListSizeGet);
#define NetPrefUtilLoginScriptLen(refNum, cxtP, scriptP) \
NetPrefUtilZStringListSizeGet ((refNum), (cxtP), \
(scriptP))
/***********************************************************************
*
* FUNCTION: NetPrefRecPhoneStringCompose
*
* DESCRIPTION: Compose a phone string from the record object.
* contcatenate the dial prefix, disable
* call waiting, calling card number, and the phone
* number
*
* PARAMETERS:
* refNum IN NetPrefLib reference number (from SysLibFind
* or SysLibLoad)
* cxtP IN Open NetPref library context as returned by
* a successful call to NetPrefLibOpen
* recP IN record object
* destP OUT string buffer to hold the complete number
* maxLen IN the allocated length of destP -1
*
* RETURNED: nothing
***********************************************************************/
extern void
NetPrefRecPhoneStringCompose (UInt16 refNum,
struct NetPrefContextTypeTag* cxtP,
struct NetPrefRecordTypeTag* recP,
Char* destP, UInt16 maxLen)
NETPREF_LIB_TRAP (netPrefLibTrapRecPhoneStringCompose);
/***********************************************************************
*
* Function: NetPrefUtilPlatformIDGet
*
* Summary: Determine on which platform we are running -- CDMA or GSM
*
* Parameters:
* nothing
*
* Returns:
* refNum IN NetPrefLib reference number (from SysLibFind
* or SysLibLoad)
* cxtP IN Open NetPref library context as returned by
* a successful call to NetPrefLibOpen -- MAY BE NULL!
* NetPrefPlatformEnum or netPrefPlatformUnknown if could not
* identify
***********************************************************************/
extern NetPrefPlatformEnum
NetPrefUtilPlatformIDGet (UInt16 refNum, struct NetPrefContextTypeTag* cxtP)
NETPREF_LIB_TRAP (netPrefLibTrapUtilPlatformIDGet);
/***********************************************************************
*
* Function: NetPrefUtilDefWirelessDriverIDGet
*
* Summary: Get the default wireless driver ID for the given platform
*
* Parameters:
* refNum IN NetPrefLib reference number (from SysLibFind
* or SysLibLoad)
* cxtP IN Open NetPref library context as returned by
* a successful call to NetPrefLibOpen -- MAY BE NULL!
* platform IN platform ID (from NetPrefUtilPlatformIDGet())
*
* Returns:
* Wireless driver ID (creator) or 0 if platform is not wireless
***********************************************************************/
extern UInt32
NetPrefUtilDefWirelessDriverIDGet (UInt16 refNum,
struct NetPrefContextTypeTag* cxtP,
NetPrefPlatformEnum platform)
NETPREF_LIB_TRAP (netPrefLibTrapUtilDefWirelessDriverIDGet);
#ifdef __cplusplus
}
#endif
#endif // _NET_PREF_LIBRARY_H_