Inherits from NSObject
Declared in RKReachabilityObserver.h
RKReachabilityObserver.m

Overview

Provides a notification based interface for monitoring changes to network status.

When initialized, creates an SCReachabilityReg and schedules it for callback notifications on the main dispatch queue. As notifications are intercepted from SystemConfiguration, the observer will update its state and emit RKReachabilityDidChangeNotifications to inform listeners about state changes.

Portions of this software are derived from the Apple Reachability code sample: http://developer.apple.com/library/ios/#samplecode/Reachability/Listings/Classes_Reachability_m.html

Tasks

Creating a Reachability Observer

  • + reachabilityObserverForHost:

    Creates and returns a RKReachabilityObserver instance observing reachability changes to the hostname or IP address referenced in a given string. The observer will monitor the ability to reach the specified remote host and emit notifications when its reachability status changes.
  • + reachabilityObserverForInternet

    Creates and returns a reachabilityObserverForInternet instance observing the reachability to the Internet in general.
  • + reachabilityObserverForLocalWifi

    Creates and returns a reachabilityObserverForInternet instance observing the reachability to the Internet via the local WiFi interface. Internet access available via the WWAN (3G, Edge, etc) will not be considered reachable.
  • + reachabilityObserverForAddress:

    Creates and returns a RKReachabilityObserver instance observing reachability changes to the sockaddr address provided.
  • + reachabilityObserverForInternetAddress:

    Creates and returns a RKReachabilityObserver instance observing reachability changes to the IP address provided.
  • – initWithHost:

    Returns a RKReachabilityObserver instance observing reachability changes to the hostname or IP address referenced in a given string. The observer will monitor the ability to reach the specified remote host and emit notifications when its reachability status changes.
  • – initWithAddress:

    Returns a RKReachabilityObserver instance observing reachability changes to the sockaddr address provided.

Determining the Host

  •   host

    The remote hostname or IP address being observed for reachability.

         property

Managing Reachability States

Reachability Introspection

Properties

host

The remote hostname or IP address being observed for reachability.

@property (nonatomic, readonly) NSString *host

Declared In

RKReachabilityObserver.h

monitoringLocalWiFi

Current state of the local WiFi interface’s reachability

@property (nonatomic, readonly, getter=isMonitoringLocalWiFi) BOOL monitoringLocalWiFi

Return Value

YES if the reachability observer is monitoring the local WiFi interface

Discussion

When the local WiFi interface is being monitored, only three reachability states are possible:

  • RKReachabilityIndeterminate
  • RKReachabilityNotReachable
  • RKReachabilityReachableViaWiFi

If the device has connectivity through a WWAN connection only it will consider the network not reachable.

See Also

Declared In

RKReachabilityObserver.h

networkStatus

Current network status as determined by examining the state of the currently cached reachabilityFlags

@property (nonatomic, readonly) RKReachabilityNetworkStatus networkStatus

Return Value

Status of the network as RKReachabilityNetworkStatus

Declared In

RKReachabilityObserver.h

reachabilityDetermined

Current state of determining reachability

@property (nonatomic, readonly, getter=isReachabilityDetermined) BOOL reachabilityDetermined

Return Value

YES if reachability has been determined

Discussion

When initialized, RKReachabilityObserver instances are in an indeterminate state to indicate that reachability status has not been yet established. After the first callback is processed by the observer, the observer will answer YES for reachabilityDetermined and networkStatus will return a determinate response.

Declared In

RKReachabilityObserver.h

reachabilityFlags

The reachability flags as of the last invocation of the reachability callback

@property (nonatomic, readonly) SCNetworkReachabilityFlags reachabilityFlags

Return Value

The most recently cached reachability flags reflecting current network status.

Discussion

Each time the reachability callback is invoked with an asynchronous update of reachability status the flags are cached and made accessible via the reachabilityFlags method.

Flags can also be directly obtained via [RKReachabilityObserver getFlags]

See Also

Declared In

RKReachabilityObserver.h

Class Methods

reachabilityObserverForAddress:

Creates and returns a RKReachabilityObserver instance observing reachability changes to the sockaddr address provided.

+ (RKReachabilityObserver *)reachabilityObserverForAddress:(const struct sockaddr *)address

Parameters

address

A socket address to determine reachability for.

Return Value

A reachability observer targeting the given socket address or nil if it could not be observed.

Declared In

RKReachabilityObserver.h

reachabilityObserverForHost:

Creates and returns a RKReachabilityObserver instance observing reachability changes to the hostname or IP address referenced in a given string. The observer will monitor the ability to reach the specified remote host and emit notifications when its reachability status changes.

+ (RKReachabilityObserver *)reachabilityObserverForHost:(NSString *)hostNameOrIPAddress

Parameters

hostNameOrIPAddress

An NSString containing a hostname or IP address to be observed.

Return Value

A reachability observer targeting the given hostname/IP address or nil if it could not be observed.

Discussion

The hostNameOrIPAddress will be introspected to determine if it contains an IP address encoded into a string or a DNS name. The observer will be configured appropriately based on the contents of the string.

Bug: Note that iOS 5 has known issues with hostname based reachability

Declared In

RKReachabilityObserver.h

reachabilityObserverForInternet

Creates and returns a reachabilityObserverForInternet instance observing the reachability to the Internet in general.

+ (RKReachabilityObserver *)reachabilityObserverForInternet

Return Value

A reachability observer targeting INADDR_ANY or nil if it could not be observed.

Declared In

RKReachabilityObserver.h

reachabilityObserverForInternetAddress:

Creates and returns a RKReachabilityObserver instance observing reachability changes to the IP address provided.

+ (RKReachabilityObserver *)reachabilityObserverForInternetAddress:(in_addr_t)internetAddress

Parameters

internetAddress

A 32-bit integer representation of an IP address

Return Value

A reachability observer targeting the given IP address or nil if it could not be observed.

Declared In

RKReachabilityObserver.h

reachabilityObserverForLocalWifi

Creates and returns a reachabilityObserverForInternet instance observing the reachability to the Internet via the local WiFi interface. Internet access available via the WWAN (3G, Edge, etc) will not be considered reachable.

+ (RKReachabilityObserver *)reachabilityObserverForLocalWifi

Return Value

A reachability observer targeting IN_LINKLOCALNETNUM or nil if it could not be observed.

Declared In

RKReachabilityObserver.h

Instance Methods

getFlags

Acquires the current network reachability flags, answering YES if successfully acquired; answering NO otherwise.

- (BOOL)getFlags

Discussion

Beware! The System Configuration framework operates synchronously by default. See Technical Q&A QA1693, Synchronous Networking On The Main Thread. Asking for flags blocks the current thread and potentially kills your iOS application if the reachability enquiry does not respond before the watchdog times out.

Declared In

RKReachabilityObserver.h

initWithAddress:

Returns a RKReachabilityObserver instance observing reachability changes to the sockaddr address provided.

- (id)initWithAddress:(const struct sockaddr *)address

Parameters

address

A socket address to determine reachability for.

Return Value

A reachability observer targeting the given socket address or nil if it could not be observed.

Declared In

RKReachabilityObserver.h

initWithHost:

Returns a RKReachabilityObserver instance observing reachability changes to the hostname or IP address referenced in a given string. The observer will monitor the ability to reach the specified remote host and emit notifications when its reachability status changes.

- (id)initWithHost:(NSString *)hostNameOrIPAddress

Parameters

hostNameOrIPAddress

An NSString containing a hostname or IP address to be observed.

Return Value

A reachability observer targeting the given hostname/IP address or nil if it could not be observed.

Discussion

The hostNameOrIPAddress will be introspected to determine if it contains an IP address encoded into a string or a DNS name. The observer will be configured appropriately based on the contents of the string.

Bug: Note that iOS 5 has known issues with hostname based reachability

Declared In

RKReachabilityObserver.h

isConnectionOnDemand

Returns YES if a dynamic, on-demand connection is available

- (BOOL)isConnectionOnDemand

Exceptions

NSInternalInconsistencyException

Raises an NSInternalInconsistencyException if called before reachability is determined

Declared In

RKReachabilityObserver.h

isConnectionRequired

Returns YES when WWAN may be available, but not active until a connection has been established.

- (BOOL)isConnectionRequired

Exceptions

NSInternalInconsistencyException

Raises an NSInternalInconsistencyException if called before reachability is determined

Declared In

RKReachabilityObserver.h

isInterventionRequired

Returns YES if user intervention is required to initiate a connection

- (BOOL)isInterventionRequired

Exceptions

NSInternalInconsistencyException

Raises an NSInternalInconsistencyException if called before reachability is determined

Declared In

RKReachabilityObserver.h

isNetworkReachable

Returns YES when the Internet is reachable (via WiFi or WWAN)

- (BOOL)isNetworkReachable

Exceptions

NSInternalInconsistencyException

Raises an NSInternalInconsistencyException if called before reachability is determined

Declared In

RKReachabilityObserver.h

isReachableViaWWAN

Returns YES when we the network is reachable via WWAN

- (BOOL)isReachableViaWWAN

Exceptions

NSInternalInconsistencyException

Raises an NSInternalInconsistencyException if called before reachability is determined

Declared In

RKReachabilityObserver.h

isReachableViaWiFi

Returns YES when we the network is reachable via WiFi

- (BOOL)isReachableViaWiFi

Exceptions

NSInternalInconsistencyException

Raises an NSInternalInconsistencyException if called before reachability is determined

Declared In

RKReachabilityObserver.h

reachabilityFlagsDescription

Returns a string representation of the currently cached reachabilityFlags for inspection

- (NSString *)reachabilityFlagsDescription

Return Value

A string containing single character representations of the bits in an SCNetworkReachabilityFlags

Declared In

RKReachabilityObserver.h