How to use iPhone with Network Status Functions: A Tutorial for Software Developers

Version 1.2 January 19

Introduction

The iPhone OS, like Mac OS X, provides both Apple specific networking functions, and Unix-type networking functions.

There are Apple specific networking functions that are prefixed with SCNetwork. For example, you can use SCNetworkReachabilityGetFlags() to return status flags as to how you can reach the network.

Another example is the Unix function call gethostbyname(). You can issue this same call on the iPhone to convert a host name into an IP address.

In this Servin Mini-Course, you will learn how to use both Apple-specific and Unix-type function calls to get network information.

iPhone Software Skills You Will Learn

How to use Xcode to create a Window-Based App.
How to display text output in a UITextView control.
How to use SCNetworkReachabilityCreateWithAddress().
How to use SCNetworkReachabilityGetFlags().
How to use gethostbyname().

Prerequisites

You should have already setup your iPhone software development environment. If this is not the case, then refer to the iPhone Flashlight App: Hands-On for Software Developers

Startup Xcode

If Xcode is not already running, start it up:

On the Mac Desktop, double-click on the Finder icon (the icon with the face on it).
On the left-side of the Finder window, click on Macintosh HD.
On the right-side of the Finder window, click on the Developer folder.
Click on the Applications folder.
Double-click on the Xcode icon.

At this point, you should see the Xcode menu at the top of your desktop.

Create New Xcode Project

With Xcode running, create a new Xcode project:

File > New Project.
On the left-side of the New Project window, select Application under iPhone OS.
On the right-side of the New Project window, select Window-Based Application.
Click on the Choose button.
Enter NetStatus for the project name.
Click on Save button.

At this point, you should see Xcode open a new window that shows a number of files.

Build Default App

Go ahead and build the default application:

Click on the Build and Go button.
After a brief moment, you should see the code running in the iPhone Simulator.
Observe the status bar at the top of the window, and a white window everywhere else.
In the iPhone Simulator, press the Home button to stop the application.

Edit NetStatusAppDelegate to Add UITextView as Subview to UIWindow

In this exercise, you will edit NetStatusAppDelegate.h and NetStatusAppDelegate.m to add a UITextView as a subview to the UIWindow.

In Xcode, in the Groups & Files window on the left-side, click on the Classes folder.
You should see the following files on the right-side of the window:
```
NetStatusAppDelegate.h
NetStatusAppDelegate.m
```
Select NetStatusAppDelegate.h so that it appears in the Xcode editor window.

Edit the code to match the following:

#import <UIKit/UIKit.h>

@interface NetStatusAppDelegate : NSObject <UIApplicationDelegate> {
	UIWindow *window;

	UITextView *textView;

}
@property (nonatomic, retain) IBOutlet UIWindow *window;

@property (nonatomic, retain) UITextView *textView;

@end

The above code adds a member variable named textView, which is a pointer to an object of type UITextView. Our goal is to use the UITextView control to display the output.
We will not use Interface Builder for this demo, so we did not add the IBOutlet to the code that we entered.
Select NetStatusAppDelegate.m into the Xcode editor window.

Edit the code to match the following:

#import <NetStatusAppDelegate.h>

@implementation NetStatusAppDelegate

@synthesize window;

@synthesize textView;


- (void)applicationDidFinishLaunching:(UIApplication *)application {

	// Create instance of UITextView
	self.textView = [[UITextView alloc] 
			 initWithFrame:[[UIScreen mainScreen] applicationFrame]];

	// Add text
	self.textView.text = @"Output will go here...";

	// Make non-editable
	self.textView.editable = NO;

	// Add as subview to window
	[window addSubview:self.textView];

	// Decrement our usage count
	[self.textView release];

	[window makeKeyAndVisible];
}

Build and Go.
You should see your app running, with the text "Output will go here..." displayed in the window.
Press Home in iPhone Simulator to stop the application.

As a review, in this exercise you added code to the NetStatusAppDelegate class to create a UITextView, setting it so that it cannot be edited. You also added text to the UITextView, and then added the UITextView to the subview of the window.

SystemConfiguration.framework

In this exercise, you will add the SystemConfiguration.framework to your project. This framework is needed, for it holds the SCNetwork functions, along with other functions related to system configuration.

In Xcode, in the Groups & Files window on the left-side, click on the Frameworks folder.

You should see the following frameworks:

- CoreGraphics.framework
- Foundation.framework
- UIKit.framework

Control+click on the Frameworks folder.
Select Add from the popup menu.
Select Existing Frameworks.
Select Frameworks folder. (This may already be selected.)
Select SystemConfiguration.framework.
Click on Add.
When prompted, confirm that you want to add the framework.

The result is that you will now have the following frameworks listed in your Frameworks folder:

- CoreGraphics.framework
- Foundation.framework
- SystemConfiguration.framework
- UIKit.framework

As a review, in this exercise you added the SystemConfiguration.framework to your project. This is needed, because the SCNetwork functions you will use later are in this framework.

SystemConfiguration/SystemConfiguration.h, netinet/in.h

In this exercise, you will add the two additional header files needed for this project:

- SystemConfiguration/SystemConfiguration.h
- netinet/in.h

In Xcode, in the Groups & Files window on the left-side, click on the Other Sources folder.
You should see the following files:
```
- main.m
- NetStatus_Prefix.pch
```
Click on NetStatus_Prefix.pch to select it into the Xcode editor.

Edit the code to match the following:

#ifdef __OBJC__
	#import <Foundation/Foundation.h>
	#import <UIKit/UIKit.h>

	#import <SystemConfiguration/SystemConfiguration.h>
	#import <netinet/in.h>

#endif

As a review, in this exercise you added the additional header files needed for this project.

SCNetworkReachabilityGetFlags()

In this exercise, you will use the SCNetworkReachabilityGetFlags() function to determine:

- Is the network reachable
- Is the network a cell phone network

In Xcode, in the Groups & Files window on the left-side, click on the Classes folder.
You should see the following files on the right-side of the window:
```
NetStatusAppDelegate.h
NetStatusAppDelegate.m
```
Select NetStatusAppDelegate.m so that it appears in the Xcode editor window.

The function we need to call is SCNetworkReachabilityGetFlags(), which has the following prototype:

Boolean
SCNetworkReachabilityGetFlags(
	SCNetworkReachabilityRef target,
	SCNetworkReachabilityFlags *flags);

As shown by the function prototype, the flags are returned using a pointer in the second parameter. However, the first parameter is a SCNetworkReachabilityRef, so we need to initialize that parameter.

Use the SCNetworkReachabilityCreateWithAddress() to create the first parameter required by the SCNetworkReachabilityGetFlags():

SCNetworkReachabilityRef
SCNetworkReachabilityCreateWithAddress(
	CFAllocatorRef allocator,
	const struct sockaddr *address)

You can set the allocator parameter to NULL to use the default allocator.
You can set the address parameter to a zero socket address to use the local machine.

Using the previous information as a guide, now edit NetStatusAppDelegate.m to match the following:

#import <NetStatusAppDelegate.h>

@implementation NetStatusAppDelegate

@synthesize window;
@synthesize textView;

- (void)applicationDidFinishLaunching:(UIApplication *)application {

	// Create instance of UITextView
	self.textView = [[UITextView alloc] 
			 initWithFrame:[[UIScreen mainScreen] applicationFrame]];

	// Part 1 - Create Internet socket addr of zero
	struct sockaddr_in zeroAddr;
	bzero(&zeroAddr, sizeof(zeroAddr));
	zeroAddr.sin_len = sizeof(zeroAddr);
	zeroAddr.sin_family = AF_INET;

	// Part 2- Create target in format need by SCNetwork
	SCNetworkReachabilityRef target = 
		SCNetworkReachabilityCreateWithAddress(NULL, (struct sockaddr *) &zeroAddr);

	// Part 3 - Get the flags
	SCNetworkReachabilityFlags flags;
	SCNetworkReachabilityGetFlags(target, &flags);

	// Part 4 - Create output
	NSString *sNetworkReachable;
	if (flags & kSCNetworkFlagsReachable)
		sNetworkReachable = @"YES";
	else
		sNetworkReachable = @"NO";

	NSString *sCellNetwork;
	if (flags & kSCNetworkReachabilityFlagsIsWWAN)
		sCellNetwork = @"YES";
	else
		sCellNetwork = @"NO";

	NSString *s = [[NSString alloc]
		       initWithFormat:
			@"Network Reachable: %@\n"
			@"Cell Network: %@\n",
		        sNetworkReachable,
			sCellNetwork];

	// Add text
	self.textView.text = s;
	[sCellNetwork release];
	[sNetworkReachable release];
	[s release];

	// Make non-editable
	self.textView.editable = NO;

	// Add as subview to window
	[window addSubview:self.textView];

	// Decrement our usage count
	[self.textView release];
	[window makeKeyAndVisible];
}

Build and Go.
When your application runs, you should see the following displayed on the iPhone screen:
```
Network Reachable: YES
Cell Network: NO
```

As a review, in this exercise you used the SCNetworkReachabilityGetFlags() function to get status related to network reachability.

Unix gethostbyname(3)

In this exercise, you will use the Unix C library function gethostbyname(3) to display the IP address of a remote host.

In Xcode, select Help > Open man page. In the world of Unix, a man page is a manual page that documents Unix commands, system calls, and other info.
When you see the Open man Page window, enter gethostbyname, then click on OK.

In the documentation window, observe the "Name" field:

endhostent, gethostbyaddr, gethostbyname - get network host entry

Observe the information shown in the Synopsis section:

#include <netdb.h>

struct hostent *
gethostbyname(const char *name);

In our case, we will use gethostbyname() to return the IP address of the host servin.com:
```
struct hostent *remoteHostEnt = gethostbyname("servin.com");
```

Scroll down further in the documentation, in the section titled Description, and find the definition of struct hostent:

struct hostent {
	char *h_name; /* official name of host */
	char **h_aliases; /* alias list */
	int h_addrtype; /* host addr type */
	int h_length; /* length of address */
	char **h_addr_list; /* list of addresses from the name server */
}

Our goal is to display the IP address for servin.com, so we need to convert from the generic h_addr_list to a specific Internet address format:
```
struct in_addr *remoteInAddr = (struct in_addr *) remoteHostEnt->h_addr_list[0];
```
To display the output, we need string data, so we convert from an Internet address to an ASCII string:
```
#include <arpa/inet.h>

char *
inet_ntoa(struct in_addr in);
```

This leads to the following code:

char *sRemoteInAddr = inet_ntoa(*remoteInAddr);

Putting all the previous comments together, you are now ready to edit the code.
In Xcode, in the Groups & Files window on the left-side, click on the Other Sources folder.
You should see the following files on the right-side of the window:
```
main.m
NetStatus_Prefix.pch
```
Select NetStatus_Prefix.pch so that it appears in the Xcode editor window.

Edit the code to match the following:

#ifdef __OBJC__
	#import <Foundation/Foundation.h>
	#import <UIKit/UIKit.h>
	#import <SystemConfiguration/SystemConfiguration.h>
	#import <netinet/in.h>

	#include <netdb.h>
	#include <arpa/inet.h>

#endif

In Xcode, in the Groups & Files window on the left-side, click on the Classes folder.
You should see the following files on the right-side of the window:
```
NetStatusAppDelegate.h
NetStatusAppDelegate.m
```
Select NetStatusAppDelegate.m into the Xcode editor.

Edit the code to match the following:

- (void)applicationDidFinishLaunching:(UIApplication *)application {

	// Create instance of UITextView
	self.textView = [[UITextView alloc] 
			 initWithFrame:[[UIScreen mainScreen] applicationFrame]];

	// Part 1 - Create Internet socket addr of zero
	struct sockaddr_in zeroAddr;
	bzero(&zeroAddr, sizeof(zeroAddr));
	zeroAddr.sin_len = sizeof(zeroAddr);
	zeroAddr.sin_family = AF_INET;

	// Part 2- Create target in format need by SCNetwork
	SCNetworkReachabilityRef target = 
		SCNetworkReachabilityCreateWithAddress(NULL, (struct sockaddr *) &zeroAddr);

	// Part 3 - Get the flags
	SCNetworkReachabilityFlags flags;
	SCNetworkReachabilityGetFlags(target, &flags);

	// Part 4 - Create output
	NSString *sNetworkReachable;
	if (flags & kSCNetworkFlagsReachable)
		sNetworkReachable = @"YES";
	else
		sNetworkReachable = @"NO";

	NSString *sCellNetwork;
	if (flags & kSCNetworkReachabilityFlagsIsWWAN)
		sCellNetwork = @"YES";
	else
		sCellNetwork = @"NO";


	// Get host entry info for given host
	struct hostent *remoteHostEnt = gethostbyname("servin.com");

	// Get address info from host entry
	struct in_addr *remoteInAddr = (struct in_addr *) remoteHostEnt->h_addr_list[0];

	// Convert numeric addr to ASCII string
	char *sRemoteInAddr = inet_ntoa(*remoteInAddr);

	NSString *s = [[NSString alloc]
		       initWithFormat:
			@"Network Reachable: %@\n"
			@"Cell Network: %@\n"
			@"Remote IP: %s\n",
			sNetworkReachable,
			sCellNetwork,
			sRemoteInAddr];


	// Add text
	self.textView.text = s;
	[sCellNetwork release];
	[sNetworkReachable release];
	[s release];
	// Make non-editable
	self.textView.editable = NO;

	// Add as subview to window
	[window addSubview:self.textView];

	// Decrement our usage count
	[self.textView release];
	[window makeKeyAndVisible];
}

Build and Go.
When your application runs, you should see an output on the screen similar to the following:
```
Network Reachable: YES
Cell Network: NO
Remote IP: 216.75.35.182
```

As a review, in this exercise you used the Unix man pages to display information about the gethostbyname(3) C-language library call, and you used the function to resolve a name to an IP address.

Skills Review

Xcode
Window-Based Application
UITextView
Help > Open man Page...
gethostbyname(3)
struct hostent
struct in_addr
inet_ntoa(3)
NSString
initWithFormat:

How To Contact Author

Feel free to contact the author for any of the following:

You have a question or comment about this mini-course.
You need to hire Servin to help with your software development project.
You need to hire Servin to give an on-site training course for your software development team.