TWiki
> Main
> Releases? > WhatsNewInMscape25 > CommunicateWithTheOutsideWorld >
NetConnection
How to tell if you are online.
Introduction
The NetConnection object is designed to provide useful information about the state of the device's network connection. You can use it to tell if you are currently connected to the internet and what your IP address is.
To create the NetConnection object right click on the Tools entry in the left hand pane of the mscape maker. Then select "Add Net Connection". This object has two events that you can use to do things in the mscape. It also has a number of properties that allow you to set options and read the current state of the network, the properties are in the bottom left of the maker.
Setting options on the NetConnection object
Destination property:
This object checks to see if you are online by going to a URL and asking for a little bit of the page at that URL to see if it gets a reply. It does not download the full page but it does need a valid page at that address. Which page it goes to and how often it does this are both set using properties. To change the properties of this object select NetConnection in the left hand panel in the maker. The properties will then be visible in the bottom left of the maker. The URL that is checked is set in the Destination property, you can set it to any page that you expect to be able to reach and think will be reliable. If you are using a private wireless network then make sure that you can get to this page from your private network.
PeriodBetweenTests property:
A tiny part of this page will be requested frequently. You can set how often by changing the "PeriodBetweenTests" property. This sets the number of seconds between the beginning of each request. Each request might take some time so you should make sure that the gap between checks is longer than the expected time for each check. Also as this test will use some data, if you expect your users to be paying for their data then you should set this property to make sure you do not use too much of their data. Each request should only be a few hundred bytes but if you check very often then this can quickly add up. If two successive tests fail then the object will now consider itself no longer connected.
Timeout property:
Each time that a request is made it will take some time for the tiny bit of the web page to come back to the player. The timeout property sets how long in seconds it will wait before considering that page unreachable and the device no longer connected. If the value of this property is too high then it will take longer for the mscape player to realise that it is no longer connected, if it's too low then you might actually be connected but still think that you are not.
Getting the status of the network connection
The NetConnection object has two properties that may only be read while the mediascape is running:
ConnectedToDestination property:
This property will be true if you are currently connected to the network.
FirstIPAddress property:
This property will return the first IP address allocated to the current device that does not hae the form 127.0.0.X (local loopback), 0.X.X.X (invalid) or 169.X.X.X (reserved). On most devices this will be the IP address used to contact that device.
Responding to network events
The NetConnection object has two events that signal changes to the network status:
GotConnectionToDestination event:
This event will be triggered when you were offline and then go online. This will trigger the first time that you got a successful reply from your destination.
LostConnectionToDestination event:
This will be triggered if two successive requests for the little bit of the specifed web page failed.
