Next Previous

Common/SimplePing.h

/*

    Copyright (C) 2016 Apple Inc. All Rights Reserved.

    See LICENSE.txt for this sample’s licensing information

    Abstract:

    An object wrapper around the low-level BSD Sockets ping function.

*/

@import Foundation;

#include <AssertMacros.h>           // for __Check_Compile_Time

NS_ASSUME_NONNULL_BEGIN

@protocol SimplePingDelegate;

/*! Controls the IP address version used by SimplePing instances.

*/

typedef NS_ENUM(NSInteger, SimplePingAddressStyle) {

    SimplePingAddressStyleAny,          ///< Use the first IPv4 or IPv6 address found; the default.

    SimplePingAddressStyleICMPv4,       ///< Use the first IPv4 address found.

    SimplePingAddressStyleICMPv6        ///< Use the first IPv6 address found.

};

/*! An object wrapper around the low-level BSD Sockets ping function.

 *  \details To use the class create an instance, set the delegate and call `-start`

 *      to start the instance on the current run loop.  If things go well you'll soon get the

 *      `-simplePing:didStartWithAddress:` delegate callback.  From there you can can call

 *      `-sendPingWithData:` to send a ping and you'll receive the

 *      `-simplePing:didReceivePingResponsePacket:sequenceNumber:` and

 *      `-simplePing:didReceiveUnexpectedPacket:` delegate callbacks as ICMP packets arrive.

 *      The class can be used from any thread but the use of any single instance must be

 *      confined to a specific thread and that thread must run its run loop.

*/

@interface SimplePing : NSObject

- (instancetype)init NS_UNAVAILABLE;

/*! Initialise the object to ping the specified host.

 *  \param hostName The DNS name of the host to ping; an IPv4 or IPv6 address in string form will

 *      work here.

 *  \returns The initialised object.

*/

- (instancetype)initWithHostName:(NSString *)hostName NS_DESIGNATED_INITIALIZER;

/*! A copy of the value passed to `-initWithHostName:`.

*/

@property (nonatomic, copy, readonly) NSString * hostName;

/*! The delegate for this object.

 *  \details Delegate callbacks are schedule in the default run loop mode of the run loop of the

 *      thread that calls `-start`.

*/

@property (nonatomic, weak, readwrite, nullable) id<SimplePingDelegate> delegate;

/*! Controls the IP address version used by the object.

 *  \details You should set this value before starting the object.

*/

@property (nonatomic, assign, readwrite) SimplePingAddressStyle addressStyle;

/*! The address being pinged.

 *  \details The contents of the NSData is a (struct sockaddr) of some form.  The

 *      value is nil while the object is stopped and remains nil on start until

 *      `-simplePing:didStartWithAddress:` is called.

*/

@property (nonatomic, copy, readonly, nullable) NSData * hostAddress;

/*! The address family for `hostAddress`, or `AF_UNSPEC` if that's nil.

*/

@property (nonatomic, assign, readonly) sa_family_t hostAddressFamily;

/*! The identifier used by pings by this object.

 *  \details When you create an instance of this object it generates a random identifier

 *      that it uses to identify its own pings.

*/

@property (nonatomic, assign, readonly) uint16_t identifier;

/*! The next sequence number to be used by this object.

 *  \details This value starts at zero and increments each time you send a ping (safely

 *      wrapping back to zero if necessary).  The sequence number is included in the ping,

 *      allowing you to match up requests and responses, and thus calculate ping times and

 *      so on.

*/

@property (nonatomic, assign, readonly) uint16_t nextSequenceNumber;

/*! Starts the object.

 *  \details You should set up the delegate and any ping parameters before calling this.

 *      If things go well you'll soon get the `-simplePing:didStartWithAddress:` delegate

 *      callback, at which point you can start sending pings (via `-sendPingWithData:`) and

 *      will start receiving ICMP packets (either ping responses, via the

 *      `-simplePing:didReceivePingResponsePacket:sequenceNumber:` delegate callback, or

 *      unsolicited ICMP packets, via the `-simplePing:didReceiveUnexpectedPacket:` delegate

 *      callback).

 *      If the object fails to start, typically because `hostName` doesn't resolve, you'll get

 *      the `-simplePing:didFailWithError:` delegate callback.

 *      It is not correct to start an already started object.

*/

- (void)start;

/*! Sends a ping packet containing the specified data.

 *  \details Sends an actual ping.

 *      The object must be started when you call this method and, on starting the object, you must

 *      wait for the `-simplePing:didStartWithAddress:` delegate callback before calling it.

 *  \param data Some data to include in the ping packet, after the ICMP header, or nil if you

 *      want the packet to include a standard 56 byte payload (resulting in a standard 64 byte

 *      ping).

*/

- (void)sendPingWithData:(nullable NSData *)data;

/*! Stops the object.

 *  \details You should call this when you're done pinging.

 *      It's safe to call this on an object that's stopped.

*/

- (void)stop;

@end

/*! A delegate protocol for the SimplePing class.

*/

@protocol SimplePingDelegate <NSObject>

@optional

/*! A SimplePing delegate callback, called once the object has started up.

 *  \details This is called shortly after you start the object to tell you that the

 *      object has successfully started.  On receiving this callback, you can call

 *      `-sendPingWithData:` to send pings.

 *      If the object didn't start, `-simplePing:didFailWithError:` is called instead.

 *  \param pinger The object issuing the callback.

 *  \param address The address that's being pinged; at the time this delegate callback

 *      is made, this will have the same value as the `hostAddress` property.

*/

- (void)simplePing:(SimplePing *)pinger didStartWithAddress:(NSData *)address;

/*! A SimplePing delegate callback, called if the object fails to start up.

 *  \details This is called shortly after you start the object to tell you that the

 *      object has failed to start.  The most likely cause of failure is a problem

 *      resolving `hostName`.

 *      By the time this callback is called, the object has stopped (that is, you don't

 *      need to call `-stop` yourself).

 *  \param pinger The object issuing the callback.

 *  \param error Describes the failure.

*/

- (void)simplePing:(SimplePing *)pinger didFailWithError:(NSError *)error;

/*! A SimplePing delegate callback, called when the object has successfully sent a ping packet.

 *  \details Each call to `-sendPingWithData:` will result in either a

 *      `-simplePing:didSendPacket:sequenceNumber:` delegate callback or a

 *      `-simplePing:didFailToSendPacket:sequenceNumber:error:` delegate callback (unless you

 *      stop the object before you get the callback).  These callbacks are currently delivered

 *      synchronously from within `-sendPingWithData:`, but this synchronous behaviour is not

 *      considered API.

 *  \param pinger The object issuing the callback.

 *  \param packet The packet that was sent; this includes the ICMP header (`ICMPHeader`) and the

 *      data you passed to `-sendPingWithData:` but does not include any IP-level headers.

 *  \param sequenceNumber The ICMP sequence number of that packet.

*/

- (void)simplePing:(SimplePing *)pinger didSendPacket:(NSData *)packet sequenceNumber:(uint16_t)sequenceNumber;

/*! A SimplePing delegate callback, called when the object fails to send a ping packet.

 *  \details Each call to `-sendPingWithData:` will result in either a

 *      `-simplePing:didSendPacket:sequenceNumber:` delegate callback or a

 *      `-simplePing:didFailToSendPacket:sequenceNumber:error:` delegate callback (unless you

 *      stop the object before you get the callback).  These callbacks are currently delivered

 *      synchronously from within `-sendPingWithData:`, but this synchronous behaviour is not

 *      considered API.

 *  \param pinger The object issuing the callback.

 *  \param packet The packet that was not sent; see `-simplePing:didSendPacket:sequenceNumber:`

 *      for details.

 *  \param sequenceNumber The ICMP sequence number of that packet.

 *  \param error Describes the failure.

*/

- (void)simplePing:(SimplePing *)pinger didFailToSendPacket:(NSData *)packet sequenceNumber:(uint16_t)sequenceNumber error:(NSError *)error;

/*! A SimplePing delegate callback, called when the object receives a ping response.

 *  \details If the object receives an ping response that matches a ping request that it

 *      sent, it informs the delegate via this callback.  Matching is primarily done based on

 *      the ICMP identifier, although other criteria are used as well.

 *  \param pinger The object issuing the callback.

 *  \param packet The packet received; this includes the ICMP header (`ICMPHeader`) and any data that

 *      follows that in the ICMP message but does not include any IP-level headers.

 *  \param sequenceNumber The ICMP sequence number of that packet.

*/

- (void)simplePing:(SimplePing *)pinger didReceivePingResponsePacket:(NSData *)packet sequenceNumber:(uint16_t)sequenceNumber;

/*! A SimplePing delegate callback, called when the object receives an unmatched ICMP message.

 *  \details If the object receives an ICMP message that does not match a ping request that it

 *      sent, it informs the delegate via this callback.  The nature of ICMP handling in a

 *      BSD kernel makes this a common event because, when an ICMP message arrives, it is

 *      delivered to all ICMP sockets.

 *      IMPORTANT: This callback is especially common when using IPv6 because IPv6 uses ICMP

 *      for important network management functions.  For example, IPv6 routers periodically

 *      send out Router Advertisement (RA) packets via Neighbor Discovery Protocol (NDP), which

 *      is implemented on top of ICMP.

 *      For more on matching, see the discussion associated with

 *      `-simplePing:didReceivePingResponsePacket:sequenceNumber:`.

 *  \param pinger The object issuing the callback.

 *  \param packet The packet received; this includes the ICMP header (`ICMPHeader`) and any data that

 *      follows that in the ICMP message but does not include any IP-level headers.

*/

- (void)simplePing:(SimplePing *)pinger didReceiveUnexpectedPacket:(NSData *)packet;

@end

#pragma mark * ICMP On-The-Wire Format

/*! Describes the on-the-wire header format for an ICMP ping.

 *  \details This defines the header structure of ping packets on the wire.  Both IPv4 and

 *      IPv6 use the same basic structure.

 *      This is declared in the header because clients of SimplePing might want to use

 *      it parse received ping packets.

*/

struct ICMPHeader {

    uint8_t     type;

    uint8_t     code;

    uint16_t    checksum;

    uint16_t    identifier;

    uint16_t    sequenceNumber;

    // data...

};

typedef struct ICMPHeader ICMPHeader;

__Check_Compile_Time(sizeof(ICMPHeader) == 8);

__Check_Compile_Time(offsetof(ICMPHeader, type) == 0);

__Check_Compile_Time(offsetof(ICMPHeader, code) == 1);

__Check_Compile_Time(offsetof(ICMPHeader, checksum) == 2);

__Check_Compile_Time(offsetof(ICMPHeader, identifier) == 4);

__Check_Compile_Time(offsetof(ICMPHeader, sequenceNumber) == 6);

enum {

    ICMPv4TypeEchoRequest = 8,          ///< The ICMP `type` for a ping request; in this case `code` is always 0.

    ICMPv4TypeEchoReply   = 0           ///< The ICMP `type` for a ping response; in this case `code` is always 0.

};

enum {

    ICMPv6TypeEchoRequest = 128,        ///< The ICMP `type` for a ping request; in this case `code` is always 0.

    ICMPv6TypeEchoReply   = 129         ///< The ICMP `type` for a ping response; in this case `code` is always 0.

};

NS_ASSUME_NONNULL_END

Next Previous