API Management and Device Selection


Functions

SWI_API SWI_RCODE SwiApiStartup (SWI_STRUCT_ApiStartup *pOpenParams)
SWI_API SWI_RCODE SwiApiShutdown ()
SWI_API SWI_RCODE SwiGetAvailAirServers (SWI_STRUCT_AirServerList &sList)
SWI_API SWI_RCODE SwiSelectAirServer (SWI_STRUCT_AirServer &airServer)
SWI_API SWI_RCODE SwiGetAirServerInfo (SWI_STRUCT_AirServer sAirServer, SWI_STRUCT_AirServerExtended &sInfo)

Function Documentation

SWI_API SWI_RCODE SwiApiShutdown (  ) 

This function is called to shut down the API sub-system. Control and status information will no longer be available after making this call. Existing internet data connections will not be affected by this call.

You must re-initialize the API using SwiApiStartup before any further API functions can be called.

Returns:
SWI_RCODE_OK: API closed successfully

See SWI_RCODE for additional information.

See also:
SwiApiStartup

See sample code, ConnectApi

SWI_API SWI_RCODE SwiApiStartup ( SWI_STRUCT_ApiStartup pOpenParams  ) 

This function is used to initialize the API sub-system.

This function must be called first before any other function calls are made.

After calling this function, SwiGetAvailAirServers can be called to retrieve a list of air servers. SwiSelectAirServer must be used to commit to a specific air server before calling any modem control and status API functions.

SwiApiStartup/SwiApiShutdown does not have to be called when device insertion/removal is detected. Simply use SwiSelectAirServer to bind to a newly inserted device.

SwiApiShutdown must be called to terminate usage of the API and release any resources allocated by the SwiApiStartup function call.

This function applies to all devices.

Parameters:
[IN] pOpenParams: Pointer to a SWI_STRUCT_ApiStartup structure which defines customizations to initialize the API
Returns:
SWI_RCODE_OK: API initialized successfully

SWI_RCODE_FAILED: The API sub-system was not initialized successfully.

SWI_RCODE_SYSTEM_ERROR: The API failed to initialize due to limited system resources when the API requested memory from the OS.

See SWI_RCODE for other error return codes

If an error is returned or to re-initialize the API,

See also:
SwiApiShutdown

SWI_STRUCT_ApiStartup

See sample code, ConnectApi

SWI_API SWI_RCODE SwiGetAirServerInfo ( SWI_STRUCT_AirServer  sAirServer,
SWI_STRUCT_AirServerExtended sInfo 
)

This function is used to retrieve additional information about a particular air server.

See SWI_STRUCT_AirServerExtended for list of additional information that can be retrieved.

Parameters:
[IN] sAirServer: A structure of type SWI_STRUCT_AirServer which specifies the the air server of interest.
[OUT]sInfo,: A structure of type SWI_STRUCT_AirServerExtended which contains additional information about the requested air server.
Returns:
SWI_RCODE_OK: Additional information successfully retrieved.

See SWI_RCODE for other error return codes.

See also:
SWI_STRUCT_AirServer

SWI_STRUCT_AirServerExtended

SWI_API SWI_RCODE SwiGetAvailAirServers ( SWI_STRUCT_AirServerList sList  ) 

This function is used to retrieve a list of available air servers.

Air servers are deemed available if the appropriate driver interface, is found. These interfaces must be capable of supporting a control and status command path to the air server. SwiSelectAirServer must be called to bind to the air server before any command and status functions are called.

Air servers locked for exclusive use by an application are also included.

Parameters:
[IN] sList: A structure of type SWI_STRUCT_AirServerList which contains a list of available air servers.
Returns:
SWI_RCODE_OK: List of available servers is successfully retrieved.

SWI_RCODE_FAILED: Failed to retrieve the list of available air servers.

See also:
SWI_STRUCT_AirServerList

SwiSelectAirServer

See sample code, ConnectApi

SWI_API SWI_RCODE SwiSelectAirServer ( SWI_STRUCT_AirServer airServer  ) 

This function is used to bind the API to a specific air server.

Use SwiGetAvailAirServers to retrieve a list of available air servers. Modem control and status API calls can not be invoked until this call is completed. The API can only bind to one air server at a time.

If the API is already bound to an air server, calling this function will cancel all pending requests and re-bind to the new air server.

Parameters:
[IN] airServer: Air server you are connecting to. This tells the API what services are supported.
Returns:
SWI_RCODE_OK: API successfully bound to air server

SWI_RCODE_FAILED: API failed to bind to new air server.

See SWI_RCODE for other error return codes.

See also:
SWI_STRUCT_AirServer


Generated on Fri Oct 2 10:27:30 2009 for 3G SDK by  doxygen 1.5.9