API Guide Home (Online version only) |

# NetMasterLibrary.h

Go to the documentation of this file.

    00001 /******************************************************************************
    00002  * Copyright (c) 2004 palmOne, Inc. or its subsidiaries.
    00003  * All rights reserved.
    00004  *****************************************************************************/
    00005 /**
    00006  * @defgroup NETMASTER NetMaster Library
    00007  *
    00008  * @{
    00009  * @}
    00010  */
    00011 /**
    00012  * @ingroup NETMASTER
    00013  */
    00014
    00015 /**
    00016  * @file    NetMasterLibrary.h
    00017  * @version 1.0
    00018  * @date    01/31/2002
    00019  *
    00020  * @brief This is the main header file for the NetMaster Library.
    00021  *
    00022  * Usage Model
    00023  *
    00024  * The NetMaster library is preloaded by the system software before
    00025  * the system sends sysAppLaunchCmdSystemReset.
    00026  *
    00027  * Clients of NetMaster library need to call SysLibFind (netMasterLibName,...)
    00028  * to get a library refNum of NetMaster.
    00029  *
    00030  * If SysLibFind returns a non-zero error, clients <b>MUST</b> assume that
    00031  * NetMaster was not loaded for a <b>good</b> reason
    00032  * (such as when the user performed a "safe" reset), or is
    00033  * simply not present on the system and fail gracefully.
    00034  *
    00035  * Clients <b>MUST NOT</b> load NetMaster themselves (such as via SysLibLoad or
    00036  * SysLibInstall) -- keep in mind that if the system didn't load it,
    00037  * there was a good reason for it!
    00038  *
    00039  */
    00040
    00041 #ifndef _NET_MASTER_LIBRARY_H_
    00042 #define _NET_MASTER_LIBRARY_H_
    00043
    00044
    00045 #include <NetMasterLibTarget.h>
    00046 #include <NetMasterLibTraps.h>
    00047 #include <NetMasterLibErrors.h>
    00048 #include <NetMasterLibTypes.h>
    00049
    00050
    00051
    00052 #ifdef BUILDING_NET_MASTER_LIB_DISPATCH_TABLE   // defined in the dispatch table
    00053                                                 // module when building the NetMaster
    00054                                                 // library itself
    00055   #define NETMASTER_LIB_TRAP(trapNum)
    00056
    00057 #else
    00058   #define NETMASTER_LIB_TRAP(trapNum) SYS_TRAP(trapNum)
    00059 #endif
    00060
    00061
    00062
    00063 #ifdef __cplusplus
    00064 extern "C" {
    00065 #endif
    00066
    00067
    00068 /// Get Library API Version number.
    00069 ///
    00070 ///  @param     refNum:     IN:  Library reference number
    00071 ///  @param     majorVerP:  OUT: Major version number
    00072 ///  @param     minorVerP:  OUT: Minor version number
    00073 ///  @param     bugFixVerP: OUT: Bug fix version number
    00074 ///  @retval    Err         NetMaster Library error code
    00075
    00076 extern Err
    00077 NetMasterLibVersionGet (UInt16 refNum, UInt32* majorVerP, UInt32* minorVerP,
    00078                         UInt32* bugFixVerP)
    00079     NETMASTER_LIB_TRAP (netMasterLibTrapLibVersionGet);
    00080
    00081
    00082 /// An extension, of sorts, of the NetLibOpen function -- allows the
    00083 /// caller to specify special options, such as "auto-dismiss on error".
    00084 /// See the definition of NetMasterNetLibOpenOptionsType for more details.
    00085 ///
    00086 /// The refNum parameter must be the refnum of NetMaster library
    00087 /// (not of NetLib).
    00088 ///
    00089 /// IMPORTANT: This call is semantically equivalent to calling NetLibOpen;
    00090 /// if this call succeeds (returns 0 error code), the caller is
    00091 /// responsible for calling NetLibClose
    00092 /// when done with NetLib; if this call fails (non-zero error code
    00093 /// returned), the caller must *NOT* make the matching call to NetLibClose.
    00094 ///
    00095 /// @param  refNum:             IN:  NetMasterLib reference number (from SysLibFind()).
    00096 /// @param  netLibOpenOptions:  IN:  See NetMasterNetLibOpenOptionsType.
    00097 /// @param  netIFErrsP          OUT: Error returned by the net interface if open failed.
    00098 /// @retval Err                 Error code.
    00099 extern Err
    00100 NetMasterNetLibOpenWithOptions (UInt16 refNum,
    00101                             NetMasterNetLibOpenOptionsType netLibOpenOptions,
    00102                             UInt16* netIFErrsP)
    00103     NETMASTER_LIB_TRAP (netMasterLibTrapNetLibOpenWithOptions);
    00104
    00105
    00106 /// Get the "auto-login" settings
    00107 ///
    00108 /// @param  refNum:     IN:  NetMasterLib reference number (from SysLibFind).
    00109 /// @param  settingsP:  OUT: Any of the NetMasterAutoLoginType constants bitwise-or’ed together.
    00110 /// @retval Err         Error code.
    00111 extern Err
    00112 NetMasterAutoLoginSettingGet (UInt16 refNum,
    00113                               NetMasterAutoLoginType* settingsP)
    00114     NETMASTER_LIB_TRAP (netMasterLibTrapAutoLoginSettingGet);
    00115
    00116
    00117 /// NetMasterAutoLoginSettingSet:
    00118 ///
    00119 /// set the "auto-login" settings
    00120 ///
    00121 /// @param  refNum:         IN:  NetMasterLib reference number.
    00122 /// @param  flagsToClear:   IN:  Flags to clear -- any of the NetMasterAutoLoginType
    00123 ///                              constants bitwise-or'ed together or
    00124 ///                              netMasterAutoLoginClearAll to clear all flags; the
    00125 ///                              flag clearing operation is performed before the
    00126 ///                              flag setting operation. Pass 0 to skip the clearing
    00127 ///                              operation.
    00128 /// @param  flagsToSet:     IN:  Flags to set -- any of the NetMasterAutoLoginType
    00129 ///                              constants bitwise-or'ed together. Pass 0 to skip the
    00130 ///                              setting operation.
    00131 /// @retval Err             Error code.
    00132 extern Err
    00133 NetMasterAutoLoginSettingSet (UInt16 refNum,
    00134                               NetMasterAutoLoginType flagsToClear,
    00135                               NetMasterAutoLoginType flagsToSet)
    00136     NETMASTER_LIB_TRAP (netMasterLibTrapAutoLoginSettingSet);
    00137
    00138
    00139 /// Function:   NetMasterNetLibOpenIfFullyUp
    00140 ///
    00141 /// Summary:    Open NetLib only if all of its current interfaces are already
    00142 ///             fully up.  If this call succeeds (returns true), it is
    00143 ///             semantically equivalent to a successful NetLibOpen call, which
    00144 ///             implies that the caller is responsible for calling NetLibClose
    00145 ///             to match this call when done with NetLib.  If
    00146 ///             NetMasterNetLibOpenIfFullyUp fails (returns false),
    00147 ///             the caller *MUST NOT* make a matching call to NetLibClose.
    00148 ///
    00149 /// @param  refNum:         IN:  NetMasterLib reference number (from SysLibFind
    00150 ///                              or SysLibLoad)
    00151 /// @param  netLibRefNumP:  OUT: NetLib refnum on success, undefined on failure
    00152 /// @retval Boolean         True if opened, false if not (failure)
    00153 extern Boolean
    00154 NetMasterNetLibOpenIfFullyUp (UInt16 refNum, UInt16* netLibRefNumP)
    00155     NETMASTER_LIB_TRAP (netMasterLibTrapNetLibOpenIfFullyUp);
    00156
    00157
    00158 /// Function:   NetMasterNetLibIsFullyUp
    00159 ///
    00160 /// Summary:    Checks if NetLib is fully up -- i.e. all of its interfaces
    00161 ///             are up.
    00162 ///
    00163 /// @param  refNum: IN:  NetMasterLib reference number (from SysLibFind
    00164 /// @retval Boolean True if NetLib is fully up, false if at least one interface is down.
    00165 extern Boolean
    00166 NetMasterNetLibIsFullyUp (UInt16 refNum)
    00167     NETMASTER_LIB_TRAP (netMasterLibTrapNetLibIsFullyUp);
    00168
    00169
    00170 /// Shut down NetLib's interfaces, if they are presently up; does nothing
    00171 /// if they are presently down; blocking;  If NetLib is in the process
    00172 /// of logging on to the IP network (Connection progress dialog is up),
    00173 /// will simulate the press of the Cancel key and return without waiting
    00174 /// for interfaces to shut down.
    00175 ///
    00176 /// WARNING: will dead-lock if called from the context of a Notification
    00177 /// Manager notification.  This is because Notification Manager erroneously
    00178 /// grabs the Memory Manager semaphore before sending a notification, and
    00179 /// this causes a dead-lock when the TCP/IP stack's background task calls
    00180 /// into Memory Manager or Data Manager API as part of the shut-down.
    00181 ///
    00182 /// Shut down NetLib’s interfaces, if they are presently up; does nothing if they are
    00183 /// presently down.
    00184 ///
    00185 /// @param  refNum:             IN: NetMasterLib reference number (from SysLibFind)
    00186 /// @param  reasonErrCode:      IN: Error code that is the reason for this call to
    00187 ///                                 NetMasterNetInterfacesShutDown; 0 if not an error, or reason is unknown.
    00188 ///                                 Future version of this API may use the error code to display an alert or log a debug trace.
    00189 /// @param  shutDownOptions:    IN: Shutdown options. See NetMasterNetIFShutDownOptionsType.
    00190 /// @retval Err Error code.
    00191 extern Err
    00192 NetMasterNetInterfacesShutDown (UInt16 refNum, Err reasonErrCode,
    00193                             NetMasterNetIFShutDownOptionsType shutDownOptions)
    00194     NETMASTER_LIB_TRAP (netMasterLibTrapNetInterfacesShutDown);
    00195
    00196
    00197 /// Test if NetLib is in the Logging On state.
    00198 /// Returns true if some client is presently inside NetLibOpen or
    00199 /// NetLibOpenConfig.
    00200 ///
    00201 /// @param  refNum:                 IN:  NetMaster library reference number.
    00202 /// @param  isLogonActiveP:         OUT: True if NetLib is in the middle of
    00203 ///                                      logging in and an error has not yet been encountered.
    00204 ///                                      This parameter is OPTIONAL -- pass NULL to ignore.
    00205 /// @param  isPrgDialogUpP:         OUT: If NetLib's Service Connection Progress
    00206 ///                                      dialog is up, NetMasterIsLoggingIn will set
    00207 ///                                      *isPrgDialogUpP to true; false otherwise.
    00208 ///                                      This parameter is OPTIONAL -- pass NULL to ignore.
    00209 /// @param  waitingInErrorStateP:   OUT: If NetLib's Service Connection Prorgress
    00210 ///                                      dialog is in the error acknowledegement state
    00211 ///                                      (displaying an error message to the user,
    00212 ///                                      waiting for OK), NetMasterIsLoggingIn will set
    00213 ///                                      *waitingInErrorStateP to true; false otherwise.
    00214 ///                                      This parameter is OPTIONAL -- pass NULL to ignore.
    00215 /// @retval Boolean                 True if some client is presently inside NetLibOpen or NetLibOpenConfig.
    00216 extern Boolean
    00217 NetMasterNetLibIsLoggingIn (UInt16 refNum, Boolean* isLogonActiveP,
    00218                             Boolean* isPrgDialogUpP,
    00219                             Boolean* waitingInErrorStateP)
    00220     NETMASTER_LIB_TRAP (netMasterLibTrapNetLibIsLoggingIn);
    00221
    00222
    00223
    00224 //-------------------------------------------------------------------------
    00225 // NetMaster Data Session Control API
    00226 //-------------------------------------------------------------------------
    00227
    00228 #if 0
    00229 #pragma mark -- Data Session Control API --
    00230 #endif
    00231
    00232
    00233 /*
    00234
    00235         Usage Model for Data Session Control API
    00236
    00237
    00238
    00239 Background:
    00240
    00241 Palm OS 5.2 does *not* provide a robust model for arbitrating the
    00242 activation (loogging in) of different network service profiles
    00243 between competing tasks.  For example, the MMS application,
    00244 running in the background, may receive a trigger and need to log
    00245 in with the MMS APN (network profile), while the Browser app
    00246 has NetLib open with the Internet or browser-specific APN.
    00247 NetLib does not provide a way to arbitrate between the needs
    00248 of both apps, and this version of NetLib and/or the initial
    00249 hardware that runs it do not support multiple concurrent data
    00250 sessions over the same Network Interface (PPP, for example). This
    00251 API attempts to bridge the gap somewhat by keeping track of the
    00252 current NetLib usage by various tasks, and trying to make
    00253 intelligent decisions about when a request to activate a
    00254 particular network profile may be allowed to shut down another
    00255 previously active profile.  This API also attempts to simplify
    00256 and make more robust the process of logging in with a network
    00257 profile that is not the "default" network profile. Before this
    00258 API, applications had to get the current default network profile
    00259 ID, set a new default, call NetLibOpen, do their networking, then
    00260 restore the default ID. This worked somewhat in a model where
    00261 only one app runs and performs data networking at a time.
    00262 However, multiple concurrent clients, possibly running on
    00263 different tasks, open lots of room for the multiple writer
    00264 problem as well as the inability to restore the default profile
    00265 ID should a crash or soft-reset occur during the application's
    00266 execution.
    00267
    00268
    00269 Disclaimer:
    00270
    00271 This API is *not* for everyone.  It is intended to be a
    00272 temporary solution to a (hopefully) temprorary limitation in
    00273 Palm OS's Network library.  Future versions of Palm OS or NetLib
    00274 may make it impossible or unnecessary for this API to be
    00275 supported, and it would then be deprecated.  Most apps that
    00276 conntect using the "default" network profile (as selected in
    00277 the Network Panel) should continue to use the standard NetLib
    00278 API (NetLibOpen and NetLibClose) in order to remain compatible
    00279 with future releases of Palm OS.
    00280
    00281
    00282 Usage Model:
    00283
    00284 1. The NetMaster Data Session Control API *MUST NOT* be
    00285 intermixed with NetLib's "session control" API, which includes
    00286 NetLibOpen, NetLibOpenConfig, NetLibOpenIfCloseWait, NetLibClose,
    00287 NetLibConnectionRefresh, NetLibIFUp, NetLibIFDown, NetLibIFAttach,
    00288 and NetLibIFDetach.  You MUST either use one set of session
    00289 control API or the other, exclusively.
    00290
    00291 2. The NetMaster Data Session Control API works closely with the
    00292 Handspring NetPref library.  Applications first look up the
    00293 desired network profile record using the NetPref library API,
    00294 then provide this record's ID to NetMasterSCNetAttach via the
    00295 netPrefRecID parameter.  This API only works with network
    00296 profiles that are managed by NetPref library.  Other profiles
    00297 are NOT supported.
    00298
    00299 3. The NetMaster Data Session Control API is centered around
    00300 the concepts of data sessions and data contexts.  A given data
    00301 session represents an established (logged-in) data session via
    00302 a specific network profile ID.  An "active" data session is one
    00303 that is believed to be logged in; otherwise it is "inactive"
    00304 A given data context represents a client (an executable such as
    00305 an application or library) that successfully attached to a data
    00306 session by calling NetMasterSCNetAttach.  Multiple data contexts
    00307 may be "attached" to a single data session. The Data Session
    00308 Control API provides functions that operation on both Data
    00309 Contexts and Data Sessions.  The functions that most clients
    00310 utilizing this API will use are NetMasterSCNetAttach,
    00311 NetMasterSCNetDetach, NetMasterSCSessionIDGetFromContext, and
    00312 NetMasterSCSessionIsActive. The remaining functions are mainly
    00313 for troubleshooting purposes.
    00314
    00315 4. A client begins networking over a particular network profile
    00316 by calling NetMasterSCNetAttach() with the desired network
    00317 profile ID and other specialized parameters. The client uses
    00318 NetMasterSCNetAttach instead of NetLib's NetLibOpen or
    00319 NetLibOpenConfig. If there is already an active
    00320 data session where the requested network profile ID was
    00321 either the primary or fallback profile, NetMasterSCNetAttach
    00322 "attaches" the caller to that data session. *See NetPref API
    00323 documenation for definition of primary and fallback profiles. If,
    00324 on the other hand, the active data session was established from
    00325 a different network profile, NetMasterSCNetAttach employs an
    00326 internal algorithm to see if it can preempt (shut down) the
    00327 active data session, and do so if it can. If it cannot make room
    00328 for a new data session by tearing down an existing data session,
    00329 the function fails.  If there was no active data session or if
    00330 one was successfully shut down to make room for the new data
    00331 session, NetMasterSCNetAttach will attempt to establish a new
    00332 data session with the requested network profile, and attach the
    00333 client to that data session.  On success, NetMasterSCNetAttach
    00334 returns an error code of 0 and a non-zero Context ID of a newly
    00335 created data context that is attached to the data session. The
    00336 returned Context ID may be passed to other functions of this API
    00337 family that require a data context ID.  This data context ID is
    00338 valid only until you destroy it by calling NetMasterSCNetDetach.
    00339 Once the Context ID is destroyed, it *MUST NOT* be passed to any
    00340 functions.  If NetMasterSCNetAttach fails, you may need to retry
    00341 at a later time.  The error code netErrAlreadyOpenWithOtherConfig
    00342 indicates that NetMasterSCNetAttach could not preempt another
    00343 active data session.  Other non-zero error codes are typically
    00344 either NetLib or NetMaster library error codes.
    00345
    00346 When the client is finished with using the network session that
    00347 was acquired with NetMasterSCNetAttach, such as when exiting the
    00348 networking application or terminating its task, etc., the client
    00349 MUST destroy the data context by calling NetMasterSCNetDetach.
    00350 User's of the NetMaster Data Session Control API call
    00351 NetMasterSCNetDetach instead of NetLibClose.
    00352
    00353 5. Once attached to a data session, the client may periodically
    00354 call NetMasterSCSessionIsActive to check if that session is
    00355 still logged in.  NetMasterSCSessionIsActive takes a data session
    00356 ID as a parameter.  Call NetMasterSCSessionIDGetFromContext
    00357 to get the data session ID from a valid data context ID.  If it
    00358 reports that the data session is *not* active, this means that
    00359 the data session was shut down for some reason, such as loss of
    00360 network coverage for an extended time, wireless mode being turned
    00361 off, preemted by another client requesting a different network
    00362 profile, etc.  When this occurs, you should destroy the data
    00363 context by calling NetMasterSCNetDetach, since this API has
    00364 *no* concept of data session re-activation. If you need to resume
    00365 your data session, you need to get a new data context via
    00366 NetMasterSCNetAttach, discussed above.
    00367
    00368 6. If the application is in a state where
    00369 the anchor timeout that it initially requested when
    00370 calling NetMasterSCNetAttach is now bigger
    00371 than necessary, the application MUST reduce its anchor
    00372 timeout to the minimum acceptable value by calling
    00373 NetMasterSCContextAnchorTimeoutSet so that other services
    00374 may be activated more quickly when necessary.
    00375
    00376
    00377 7. The remaining NetMaster Data Session Control API's are
    00378 intended for troubleshooting purposes and not described in detail
    00379 yet.
    00380
    00381 */
    00382
    00383
    00384
    00385 // IMPORTANT: NetMasterSCNetAttach/NetMasterSCNetDetach are implemented under
    00386 // Palm OS 5.x only and not available before Palm OS 5.0.  These functions
    00387 // may be used from UI and background tasks. These functions semantically
    00388 // replace NetLibOpen/NetLibClose.
    00389 //
    00390 // Attach to the network using the specified service; this will call
    00391 //  NetLibOpen and execute any required fallback services, as necessary
    00392 //  on the caller's behalf.
    00393 //
    00394 // loginPriority        IN  Login priority -- most applications should use
    00395 //                           the netMasterLoginPriorityDefault priority.
    00396 //
    00397 // anchorTimeoutSec     IN  Initial data session anchor timeout request.
    00398 //                           The system may limit this request if it is bigger
    00399 //                           than maximum allowed for the given device
    00400 //                           configuration.  This value is used by the system
    00401 //                           to decide when a data session may be considered
    00402 //                           idle, and may be shut down to make room for
    00403 //                           a different login request. This value is treated
    00404 //                           as a hint only, and the system makes no
    00405 //                           guarantees about the longevity of the data
    00406 //                           session. The duration is in seconds, which may
    00407 //                           be 0.  For system default, pass
    00408 //                           netMasterAnchorTimeoutDefault (RECOMMENDED!)
    00409 //
    00410 // isNetIFErrorP        OUT [OPTIONAL] when non zero error code is returned,
    00411 //                           this boolean indicates whether the error
    00412 //                           was from the network interface. For
    00413 //                           foreground-initiated logins, the
    00414 //                           implication is that if it *is* an
    00415 //                           error from the network interface,
    00416 //                           an error message was most likely
    00417 //                           already displayed to the user via the
    00418 //                           standard progress dialog UI. If
    00419 //                           the error is *not* from the network
    00420 //                           interface, no error has been displayed
    00421 //                           to the user. Pass NULL to ignore this
    00422 //                           parameter..
    00423 //
    00424 // IMPORTANT: if this call succeeds (returns 0
    00425 //  error code), the caller is responsible for calling NetMasterSCNetDetach
    00426 //  when done with this data context; if this call fails (non-zero error code
    00427 //  returned), the caller must *NOT* make the matching call to
    00428 //  NetMasterSCNetDetach.
    00429
    00430
    00431 /// Attach to the network using the specified service; this will call NetLibOpen and
    00432 /// execute any required fallback services, as necessary on the caller’s behalf.
    00433 ///
    00434 /// @param refNum:              IN:  NetMasterLib reference number (from SysLibFind).
    00435 /// @param netPrefRecID:        IN:  NetPref Record ID of the network profile to attach.
    00436 /// @param netLibOpenOptions:   IN:  Special options, such as “auto-dismiss on error”; 0 = no options.
    00437 /// @param loginPriority:       IN:  Login priority. Most applications should use the netMasterLoginPriorityDefault priority.
    00438 /// @param anchorTimeoutSec:    IN:  It is bigger than maximum allowed for the given device configuration. This
    00439 ///                                  value is used by the system to decide when a data session may be considered
    00440 ///                                  idle, and may be shut down to make room for a different login request. This
    00441 ///                                  value is treated as a hint only, and the system makes no guarantees about the
    00442 ///                                  longevity of the data session. The duration is in seconds, which may be 0. For
    00443 ///                                  system default, pass netMasterAnchorTimeoutDefault (RECOMMENDED!)
    00444 /// @param dataCxtIDP:          OUT: Data context on success, undefined on failure.
    00445 /// @param isNetIFErrorP:       OUT: When non zero error code is returned, this boolean indicates
    00446 ///                                  whether the error was from the network interface. For foreground-initiated
    00447 ///                                  logins, the implication is that if it *is* an error from the network interface, an
    00448 ///                                  error message was most likely already displayed to the user via the standard
    00449 ///                                  progress dialog UI. If the error is *not* from the network interface, no error has
    00450 ///                                  been displayed to the user. Pass NULL to ignore this parameter.
    00451 /// @retval Err                 Error code.
    00452 extern Err
    00453 NetMasterSCNetAttach (UInt16 refNum, UInt32 netPrefRecID,
    00454                     NetMasterNetLibOpenOptionsType netLibOpenOptions,
    00455                     NetMasterLoginPriorityEnum loginPriority,
    00456                     Int32 anchorTimeoutSec,
    00457                     NetMasterDataContextIDType* dataCxtIDP,
    00458                     Boolean* isNetIFErrorP)
    00459     NETMASTER_LIB_TRAP (netMasterLibTrapSCNetAttach);
    00460
    00461 /// Detach from the data session that was successfully established by
    00462 /// NetMasterSCNetAttach.
    00463 ///
    00464 /// @param  refNum:      IN: NetMasterLib reference number (from SysLibFind).
    00465 /// @param  dataCxtID:   IN: Data context created by NetMasterSCNetAttach.
    00466 /// @retval Err          Error code.
    00467 extern Err
    00468 NetMasterSCNetDetach (UInt16 refNum,
    00469                     NetMasterDataContextIDType dataCxtID)
    00470     NETMASTER_LIB_TRAP (netMasterLibTrapSCNetDetach);
    00471
    00472
    00473 /// Changes the data context's session anchor timeout value.
    00474 /// The requested anchor timeout value is in seconds. The system
    00475 /// will apply internal limits to the value if necessary. The
    00476 /// actual value is returned via the optional output arugment
    00477 /// oActualAnchorTimeoutSecP (pass NULL to ignore).
    00478 ///
    00479 /// IMPORTANT:
    00480 /// If the application is in a state where
    00481 /// the anchor timeout that it initially requested when
    00482 /// calling NetMasterSCNetAttach is now bigger
    00483 /// than necessary, the application MUST reduce its anchor
    00484 /// timeout to the minimum acceptable value so that other services
    00485 /// may be activated more quickly when necessary.
    00486 ///
    00487 /// @param refNum:                      IN:  NetMasterLib reference number (from SysLibFind).
    00488 /// @param dataCxtID:                   IN:  Data context created by NetMasterSCNetAttach.
    00489 /// @param requestedAnchorTimeoutSec:   IN:  Requested anchor timeout in seconds.
    00490 /// @param oActualAnchorTimeoutSecP:    OUT: Actual anchor timeout that was applied (pass NULL to ignore).
    00491 ///                                          Undefined on error.
    00492 /// @retval Err                         Error code.
    00493 extern Err
    00494 NetMasterSCContextAnchorTimeoutSet (UInt16 refNum,
    00495                                     NetMasterDataContextIDType dataCxtID,
    00496                                     Int32 requestedAnchorTimeoutSec,
    00497                                     Int32* oActualAnchorTimeoutSecP)
    00498     NETMASTER_LIB_TRAP (netMasterLibTrapSCContextAnchorTimeoutSet);
    00499
    00500
    00501
    00502 /// Given a data context, get the associated data session ID.  0 or more
    00503 /// data contexts may be associated with a data session.  A data session
    00504 /// represents a single network login instance.  i.e., if you had two
    00505 /// concurrent network login instances, such as GPRS and 802.11 for example,
    00506 /// there would be two network data sessions.
    00507 ///
    00508 /// @param refNum:      IN:  NetMasterLib reference number (from SysLibFind).
    00509 /// @param dataCxtID:   IN:  Data context created by NetMasterSCNetAttach.
    00510 /// @param sessionP:    OUT: Data session ID on success, undefined on failure.
    00511 /// @retval Err         Error code.
    00512 extern Err
    00513 NetMasterSCSessionIDGetFromContext (UInt16 refNum,
    00514                                    NetMasterDataContextIDType dataCxtID,
    00515                                    NetMasterDataSessionIDType* sessionP)
    00516     NETMASTER_LIB_TRAP (netMasterLibTrapSCSessionIDGetFromContext);
    00517
    00518
    00519 /// Get the current count of network data sessions that are active (believed
    00520 /// to be logged in).
    00521 ///
    00522 /// @param refNum:              IN:  NetMasterLib reference number (from SysLibFind).
    00523 /// @param activeSessionCountP: OUT: Count of active data sessions.
    00524 /// @retval Err                 Error code.
    00525 extern Err
    00526 NetMasterSCSessionCountGet (UInt16 refNum, Int16* activeSessionCountP)
    00527     NETMASTER_LIB_TRAP (netMasterLibTrapSCSessionCountGet);
    00528
    00529
    00530 /// Fill an array with session ID's of the currently active data sessions.
    00531 /// Initially, only one active data session may be supported, but this may
    00532 /// increase with the hardware and system software capabilities.
    00533 ///
    00534 /// @param refNum:          IN:  NetMasterLib reference number (from SysLibFind).
    00535 /// @param sessionIDs:      OUT: Array for returning session IDs on success, contents undefined on failure.
    00536 /// @param maxEntries:      IN:  Max # of session ID’s that may be stored in the caller’s array sessionIDs.
    00537 /// @param entriesStoredP:  OUT: On success, number of entries that were actually returned in the sessionIDs
    00538 ///                              array, which may be less than maxEntries (possibly 0); undefined on failure.
    00539 /// @param Err              Error code.
    00540 extern Err
    00541 NetMasterSCSessionsEnumerate (UInt16 refNum,
    00542                               NetMasterDataSessionIDType sessionIDs[],
    00543                               Int16 maxEntries, Int16* entriesStoredP)
    00544     NETMASTER_LIB_TRAP (netMasterLibTrapSCSessionsEnumerate);
    00545
    00546
    00547 /// Retrieves the unique ID's of the actual and primary NetPref records
    00548 /// that were used to establish the data session. The two may be different if
    00549 /// the primary record had a fallback, the primary failed, and the fallback
    00550 /// record succeeded.  In other words, *actualNetPrefIDP indicates the NetPref
    00551 /// record ID that succeeded in establishing the connection.
    00552 ///
    00553 /// @param refNum:              IN:  NetMasterLib reference number (from SysLibFind).
    00554 /// @param sessionID:           IN:  Data session ID.
    00555 /// @param primaryNetPrefIDP:   OUT: NetPref record ID of the primary record used in connection establishment.
    00556 /// @param actualNetPrefIDP:    OUT: NetPref record ID of the actual record with which connection establishment
    00557 ///                                  succeeded. This may be the same as the primary record or a fallback of the
    00558 ///                                  primary record.
    00559 /// @retval Err                 Error code.
    00560 extern Err
    00561 NetMasterSCSessionSvcRecIDGet (UInt16 refNum,
    00562                              NetMasterDataSessionIDType sessionID,
    00563                              UInt32* primaryNetPrefIDP,
    00564                              UInt32* actualNetPrefIDP)
    00565     NETMASTER_LIB_TRAP (netMasterLibTrapSCSessionSvcRecIDGet);
    00566
    00567
    00568 /// Checks if the given session is still on the active list (believed
    00569 /// to be logged in).
    00570 ///
    00571 /// @param refNum:      IN:  NetMasterLib reference number (from SysLibFind).
    00572 /// @param sessionID:   IN:  Data session ID.
    00573 /// @param isActiveP:   OUT: True if the given session is believed to be logged in, false if it’s not logged in.
    00574 /// @retval Err         Error code.
    00575 extern Err
    00576 NetMasterSCSessionIsActive (UInt16 refNum,
    00577                             NetMasterDataSessionIDType sessionID,
    00578                             Boolean* isActiveP)
    00579     NETMASTER_LIB_TRAP (netMasterLibTrapSCSessionIsActive);
    00580
    00581
    00582 /// Request shut down of the given network session.  This
    00583 /// function may block for a significant period of time (typically
    00584 /// multiple seconds) while the network interfaces are being brought
    00585 /// down.
    00586 ///
    00587 /// @param refNum:          IN: NetMasterLib reference number (from SysLibFind).
    00588 /// @param sessionID:       IN: data session ID.
    00589 /// @param shutDownOptions: IN: shutdown options. See NetMasterNetIFShutDownOptionsType.
    00590 /// @retval Err             Error code.
    00591 extern Err
    00592 NetMasterSCSessionShutDown (UInt16 refNum,
    00593                             NetMasterDataSessionIDType sessionID,
    00594                             NetMasterNetIFShutDownOptionsType shutDownOptions)
    00595     NETMASTER_LIB_TRAP (netMasterLibTrapSCSessionShutDown);
    00596
    00597
    00598
    00599 #ifdef __cplusplus
    00600 }
    00601 #endif
    00602
    00603
    00604 #endif // _NET_MASTER_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