(Online version only)
|
API Guide Home (Online version only) |
|
The NetMaster library is preloaded by the system software before the system sends sysAppLaunchCmdSystemReset.
Clients of NetMaster library need to call SysLibFind (netMasterLibName,...) to get a library refNum of NetMaster.
If SysLibFind returns a non-zero error, clients MUST assume that NetMaster was not loaded for a good reason (such as when the user performed a "safe" reset), or is simply not present on the system and fail gracefully.
Clients MUST NOT load NetMaster themselves (such as via SysLibLoad or SysLibInstall) -- keep in mind that if the system didn't load it, there was a good reason for it!
Definition in file NetMasterLibrary.h.
Include dependency graph for NetMasterLibrary.h:
Go to the source code of this file.
| #define NETMASTER_LIB_TRAP | ( | trapNum | ) | SYS_TRAP(trapNum) |
Definition at line 58 of file NetMasterLibrary.h.
| Err NetMasterAutoLoginSettingGet | ( | UInt16 | refNum, | |
| NetMasterAutoLoginType * | settingsP | |||
| ) |
Get the "auto-login" settings
| refNum,: | IN: NetMasterLib reference number (from SysLibFind). | |
| settingsP,: | OUT: Any of the NetMasterAutoLoginType constants bitwise-or’ed together. |
| Err | Error code. |
| Err NetMasterAutoLoginSettingSet | ( | UInt16 | refNum, | |
| NetMasterAutoLoginType | flagsToClear, | |||
| NetMasterAutoLoginType | flagsToSet | |||
| ) |
NetMasterAutoLoginSettingSet:
set the "auto-login" settings
| refNum,: | IN: NetMasterLib reference number. | |
| flagsToClear,: | IN: Flags to clear -- any of the NetMasterAutoLoginType constants bitwise-or'ed together or netMasterAutoLoginClearAll to clear all flags; the flag clearing operation is performed before the flag setting operation. Pass 0 to skip the clearing operation. | |
| flagsToSet,: | IN: Flags to set -- any of the NetMasterAutoLoginType constants bitwise-or'ed together. Pass 0 to skip the setting operation. |
| Err | Error code. |
| Err NetMasterLibVersionGet | ( | UInt16 | refNum, | |
| UInt32 * | majorVerP, | |||
| UInt32 * | minorVerP, | |||
| UInt32 * | bugFixVerP | |||
| ) |
Get Library API Version number.
| refNum,: | IN: Library reference number | |
| majorVerP,: | OUT: Major version number | |
| minorVerP,: | OUT: Minor version number | |
| bugFixVerP,: | OUT: Bug fix version number |
| Err | NetMaster Library error code |
| Err NetMasterNetInterfacesShutDown | ( | UInt16 | refNum, | |
| Err | reasonErrCode, | |||
| NetMasterNetIFShutDownOptionsType | shutDownOptions | |||
| ) |
Shut down NetLib's interfaces, if they are presently up; does nothing if they are presently down; blocking; If NetLib is in the process of logging on to the IP network (Connection progress dialog is up), will simulate the press of the Cancel key and return without waiting for interfaces to shut down.
WARNING: will dead-lock if called from the context of a Notification Manager notification. This is because Notification Manager erroneously grabs the Memory Manager semaphore before sending a notification, and this causes a dead-lock when the TCP/IP stack's background task calls into Memory Manager or Data Manager API as part of the shut-down.
Shut down NetLib’s interfaces, if they are presently up; does nothing if they are presently down.
| refNum,: | IN: NetMasterLib reference number (from SysLibFind) | |
| reasonErrCode,: | IN: Error code that is the reason for this call to NetMasterNetInterfacesShutDown; 0 if not an error, or reason is unknown. Future version of this API may use the error code to display an alert or log a debug trace. | |
| shutDownOptions,: | IN: Shutdown options. See NetMasterNetIFShutDownOptionsType. |
| Err | Error code. |
Function: NetMasterNetLibIsFullyUp
Summary: Checks if NetLib is fully up -- i.e. all of its interfaces are up.
| refNum,: | IN: NetMasterLib reference number (from SysLibFind |
| Boolean | True if NetLib is fully up, false if at least one interface is down. |
| Boolean NetMasterNetLibIsLoggingIn | ( | UInt16 | refNum, | |
| Boolean * | isLogonActiveP, | |||
| Boolean * | isPrgDialogUpP, | |||
| Boolean * | waitingInErrorStateP | |||
| ) |
Test if NetLib is in the Logging On state. Returns true if some client is presently inside NetLibOpen or NetLibOpenConfig.
| refNum,: | IN: NetMaster library reference number. | |
| isLogonActiveP,: | OUT: True if NetLib is in the middle of logging in and an error has not yet been encountered. This parameter is OPTIONAL -- pass NULL to ignore. | |
| isPrgDialogUpP,: | OUT: If NetLib's Service Connection Progress dialog is up, NetMasterIsLoggingIn will set isPrgDialogUpP to true; false otherwise. This parameter is OPTIONAL -- pass NULL to ignore. | |
| waitingInErrorStateP,: | OUT: If NetLib's Service Connection Prorgress dialog is in the error acknowledegement state (displaying an error message to the user, waiting for OK), NetMasterIsLoggingIn will set waitingInErrorStateP to true; false otherwise. This parameter is OPTIONAL -- pass NULL to ignore. |
| Boolean | True if some client is presently inside NetLibOpen or NetLibOpenConfig. |
Function: NetMasterNetLibOpenIfFullyUp
Summary: Open NetLib only if all of its current interfaces are already fully up. If this call succeeds (returns true), it is semantically equivalent to a successful NetLibOpen call, which implies that the caller is responsible for calling NetLibClose to match this call when done with NetLib. If NetMasterNetLibOpenIfFullyUp fails (returns false), the caller *MUST NOT* make a matching call to NetLibClose.
| refNum,: | IN: NetMasterLib reference number (from SysLibFind or SysLibLoad) | |
| netLibRefNumP,: | OUT: NetLib refnum on success, undefined on failure |
| Boolean | True if opened, false if not (failure) |
| Err NetMasterNetLibOpenWithOptions | ( | UInt16 | refNum, | |
| NetMasterNetLibOpenOptionsType | netLibOpenOptions, | |||
| UInt16 * | netIFErrsP | |||
| ) |
An extension, of sorts, of the NetLibOpen function -- allows the caller to specify special options, such as "auto-dismiss on error". See the definition of NetMasterNetLibOpenOptionsType for more details.
The refNum parameter must be the refnum of NetMaster library (not of NetLib).
IMPORTANT: This call is semantically equivalent to calling NetLibOpen; if this call succeeds (returns 0 error code), the caller is responsible for calling NetLibClose when done with NetLib; if this call fails (non-zero error code returned), the caller must *NOT* make the matching call to NetLibClose.
| refNum,: | IN: NetMasterLib reference number (from SysLibFind()). | |
| netLibOpenOptions,: | IN: See NetMasterNetLibOpenOptionsType. | |
| netIFErrsP | OUT: Error returned by the net interface if open failed. |
| Err | Error code. |
| Err NetMasterSCContextAnchorTimeoutSet | ( | UInt16 | refNum, | |
| NetMasterDataContextIDType | dataCxtID, | |||
| Int32 | requestedAnchorTimeoutSec, | |||
| Int32 * | oActualAnchorTimeoutSecP | |||
| ) |
Changes the data context's session anchor timeout value. The requested anchor timeout value is in seconds. The system will apply internal limits to the value if necessary. The actual value is returned via the optional output arugment oActualAnchorTimeoutSecP (pass NULL to ignore).
IMPORTANT: If the application is in a state where the anchor timeout that it initially requested when calling NetMasterSCNetAttach is now bigger than necessary, the application MUST reduce its anchor timeout to the minimum acceptable value so that other services may be activated more quickly when necessary.
| refNum,: | IN: NetMasterLib reference number (from SysLibFind). | |
| dataCxtID,: | IN: Data context created by NetMasterSCNetAttach. | |
| requestedAnchorTimeoutSec,: | IN: Requested anchor timeout in seconds. | |
| oActualAnchorTimeoutSecP,: | OUT: Actual anchor timeout that was applied (pass NULL to ignore). Undefined on error. |
| Err | Error code. |
| Err NetMasterSCNetAttach | ( | UInt16 | refNum, | |
| UInt32 | netPrefRecID, | |||
| NetMasterNetLibOpenOptionsType | netLibOpenOptions, | |||
| NetMasterLoginPriorityEnum | loginPriority, | |||
| Int32 | anchorTimeoutSec, | |||
| NetMasterDataContextIDType * | dataCxtIDP, | |||
| Boolean * | isNetIFErrorP | |||
| ) |
Attach to the network using the specified service; this will call NetLibOpen and execute any required fallback services, as necessary on the caller’s behalf.
| refNum,: | IN: NetMasterLib reference number (from SysLibFind). | |
| netPrefRecID,: | IN: NetPref Record ID of the network profile to attach. | |
| netLibOpenOptions,: | IN: Special options, such as “auto-dismiss on error”; 0 = no options. | |
| loginPriority,: | IN: Login priority. Most applications should use the netMasterLoginPriorityDefault priority. | |
| anchorTimeoutSec,: | IN: It is bigger than maximum allowed for the given device configuration. This value is used by the system to decide when a data session may be considered idle, and may be shut down to make room for a different login request. This value is treated as a hint only, and the system makes no guarantees about the longevity of the data session. The duration is in seconds, which may be 0. For system default, pass netMasterAnchorTimeoutDefault (RECOMMENDED!) | |
| dataCxtIDP,: | OUT: Data context on success, undefined on failure. | |
| isNetIFErrorP,: | OUT: When non zero error code is returned, this boolean indicates whether the error was from the network interface. For foreground-initiated logins, the implication is that if it *is* an error from the network interface, an error message was most likely already displayed to the user via the standard progress dialog UI. If the error is *not* from the network interface, no error has been displayed to the user. Pass NULL to ignore this parameter. |
| Err | Error code. |
| Err NetMasterSCNetDetach | ( | UInt16 | refNum, | |
| NetMasterDataContextIDType | dataCxtID | |||
| ) |
Detach from the data session that was successfully established by NetMasterSCNetAttach.
| refNum,: | IN: NetMasterLib reference number (from SysLibFind). | |
| dataCxtID,: | IN: Data context created by NetMasterSCNetAttach. |
| Err | Error code. |
Get the current count of network data sessions that are active (believed to be logged in).
| refNum,: | IN: NetMasterLib reference number (from SysLibFind). | |
| activeSessionCountP,: | OUT: Count of active data sessions. |
| Err | Error code. |
| Err NetMasterSCSessionIDGetFromContext | ( | UInt16 | refNum, | |
| NetMasterDataContextIDType | dataCxtID, | |||
| NetMasterDataSessionIDType * | sessionP | |||
| ) |
Given a data context, get the associated data session ID. 0 or more data contexts may be associated with a data session. A data session represents a single network login instance. i.e., if you had two concurrent network login instances, such as GPRS and 802.11 for example, there would be two network data sessions.
| refNum,: | IN: NetMasterLib reference number (from SysLibFind). | |
| dataCxtID,: | IN: Data context created by NetMasterSCNetAttach. | |
| sessionP,: | OUT: Data session ID on success, undefined on failure. |
| Err | Error code. |
| Err NetMasterSCSessionIsActive | ( | UInt16 | refNum, | |
| NetMasterDataSessionIDType | sessionID, | |||
| Boolean * | isActiveP | |||
| ) |
Checks if the given session is still on the active list (believed to be logged in).
| refNum,: | IN: NetMasterLib reference number (from SysLibFind). | |
| sessionID,: | IN: Data session ID. | |
| isActiveP,: | OUT: True if the given session is believed to be logged in, false if it’s not logged in. |
| Err | Error code. |
| Err NetMasterSCSessionsEnumerate | ( | UInt16 | refNum, | |
| NetMasterDataSessionIDType | sessionIDs[], | |||
| Int16 | maxEntries, | |||
| Int16 * | entriesStoredP | |||
| ) |
Fill an array with session ID's of the currently active data sessions. Initially, only one active data session may be supported, but this may increase with the hardware and system software capabilities.
| refNum,: | IN: NetMasterLib reference number (from SysLibFind). | |
| sessionIDs,: | OUT: Array for returning session IDs on success, contents undefined on failure. | |
| maxEntries,: | IN: Max # of session ID’s that may be stored in the caller’s array sessionIDs. | |
| entriesStoredP,: | OUT: On success, number of entries that were actually returned in the sessionIDs array, which may be less than maxEntries (possibly 0); undefined on failure. | |
| Err | Error code. |
| Err NetMasterSCSessionShutDown | ( | UInt16 | refNum, | |
| NetMasterDataSessionIDType | sessionID, | |||
| NetMasterNetIFShutDownOptionsType | shutDownOptions | |||
| ) |
Request shut down of the given network session. This function may block for a significant period of time (typically multiple seconds) while the network interfaces are being brought down.
| refNum,: | IN: NetMasterLib reference number (from SysLibFind). | |
| sessionID,: | IN: data session ID. | |
| shutDownOptions,: | IN: shutdown options. See NetMasterNetIFShutDownOptionsType. |
| Err | Error code. |
| Err NetMasterSCSessionSvcRecIDGet | ( | UInt16 | refNum, | |
| NetMasterDataSessionIDType | sessionID, | |||
| UInt32 * | primaryNetPrefIDP, | |||
| UInt32 * | actualNetPrefIDP | |||
| ) |
Retrieves the unique ID's of the actual and primary NetPref records that were used to establish the data session. The two may be different if the primary record had a fallback, the primary failed, and the fallback record succeeded. In other words, *actualNetPrefIDP indicates the NetPref record ID that succeeded in establishing the connection.
| refNum,: | IN: NetMasterLib reference number (from SysLibFind). | |
| sessionID,: | IN: Data session ID. | |
| primaryNetPrefIDP,: | OUT: NetPref record ID of the primary record used in connection establishment. | |
| actualNetPrefIDP,: | OUT: NetPref record ID of the actual record with which connection establishment succeeded. This may be the same as the primary record or a fallback of the primary record. |
| Err | Error code. |
| Top | Palm Developer Network © 2004-2008, Palm, Inc. All rights reserved. Generated on Fri Jun 13 10:07:38 2008 for Palm API Guide |