//
//  KSReachability.h
//
//  Created by Karl Stenerud on 2012-05-05.
//
//  Copyright (c) 2012 Karl Stenerud. All rights reserved.
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall remain in place
// in this source code.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
// THE SOFTWARE.
//

#import <Foundation/Foundation.h>
#import "KSSystemCapabilities.h"
#if KSCRASH_HAS_REACHABILITY
#import <SystemConfiguration/SystemConfiguration.h>
#endif

/** This is the notification name used in the Apple reachability example. */
#define kDefaultNetworkReachabilityChangedNotification @"kNetworkReachabilityChangedNotification"

/** Monitors network connectivity.
 *
 * Note: Upon construction, this object will fetch its initial reachability
 * state in the background. This means that the reachability status will ALWAYS
 * be "unreachable" until some time after object construction. If you want
 * the true reachability state before the current code block ends, you can call
 * updateFlags. Note, however, that it will probably block.
 *
 * You can elect to be notified via blocks (onReachabilityChanged),
 * notifications (notificationName), or KVO (flags, reachable, and WWANOnly).
 *
 * All notification methods are disabled by default.
 */
@interface KSReachabilityKSCrash : NSObject

#pragma mark Constructors

/** Reachability to a specific host.
 *
 * @param hostname The name or IP address of the host to monitor. If nil or
 *                 empty string, check reachability to the internet in general.
 */
+ (KSReachabilityKSCrash *)reachabilityToHost:(NSString *)hostname;

/** Reachability to the local (wired or wifi) network.
 */
+ (KSReachabilityKSCrash *)reachabilityToLocalNetwork;

#pragma mark General Information

/** The host we are monitoring reachability to, if any. */
@property(nonatomic, readonly, copy) NSString *hostname;

#pragma mark Notifications and Callbacks

/** If non-nil, called whenever reachability flags change.
 * Block will be invoked on the main thread.
 */
@property(nonatomic, readwrite, copy) void (^onReachabilityChanged)(KSReachabilityKSCrash *reachability);

/** The notification to send when reachability changes (nil = don't send).
 * Default = nil
 */
@property(nonatomic, readwrite, copy) NSString *notificationName;

#pragma mark KVO Compliant Status Properties

/** The current reachability flags. */
#if KSCRASH_HAS_REACHABILITY
@property(nonatomic, readonly, assign) SCNetworkReachabilityFlags flags;
#endif

/** Whether the host is reachable or not. */
@property(nonatomic, readonly, assign) BOOL reachable;

/* If YES, the host is only reachable by WWAN (iOS only). */
@property(nonatomic, readonly, assign) BOOL WWANOnly;

#pragma mark Utility

/** Force updating of the reachability flags.
 * This method will potentially block.
 *
 * @return YES if the flags were successfully updated.
 */
- (BOOL)updateFlags;

@end

/** A one-time operation to perform as soon as a host is deemed reachable.
 * The operation will only be performed once, regardless of how many times a
 * host becomes reachable.
 */
@interface KSReachableOperationKSCrash : NSObject

/** Constructor.
 *
 * @param hostname The name or IP address of the host to monitor. If nil or
 *                 empty string, check reachability to the internet in general.
 *                 If hostname is a URL string, it will use the host portion.
 *
 * @param allowWWAN If NO, a WWAN-only connection is not enough to trigger
 *                  this operation.
 *
 * @param block The block to invoke when the host becomes reachable.
 *              Block will be invoked on the main thread.
 */
+ (KSReachableOperationKSCrash *)operationWithHost:(NSString *)hostname
                                         allowWWAN:(BOOL)allowWWAN
                                             block:(void (^)(void))block;

/** Constructor.
 *
 * @param hostname The name or IP address of the host to monitor. If nil or
 *                 empty string, check reachability to the internet in general.
 *                 If hostname is a URL string, it will use the host portion.
 *
 * @param allowWWAN If NO, a WWAN-only connection is not enough to trigger
 *                  this operation.
 *
 * @param block The block to invoke when the host becomes reachable.
 *              Block will be invoked on the main thread.
 */
- (id)initWithHost:(NSString *)hostname allowWWAN:(BOOL)allowWWAN block:(void (^)(void))block;

@end
