FMPingFoundation Class Reference

Inherits from NSObject
Declared in FMPingFoundation.h
FMPingFoundation.m

Overview

Calculates an IP checksum.

This is the standard BSD checksum code, modified to use modern types.

Other Methods

– initWithHostName:

Initialise the object to ping the specified host.

- (instancetype)initWithHostName:(NSString *)hostName

Parameters

hostName

The DNS name of the host to ping; an IPv4 or IPv6 address in string form will work here.

Return Value

The initialised object.

Discussion

Initialise the object to ping the specified host.

Declared In

FMPingFoundation.h

– hostAddressFamily

The address family for hostAddress, or AF_UNSPEC if that’s nil.

- (sa_family_t)hostAddressFamily

Discussion

The address family for hostAddress, or AF_UNSPEC if that’s nil.

Declared In

FMPingFoundation.h

– didFailWithError:

Shuts down the pinger object and tell the delegate about the error.

- (void)didFailWithError:(NSError *)error

Parameters

error

Describes the failure.

Discussion

Shuts down the pinger object and tell the delegate about the error.

Declared In

FMPingFoundation.m

– didFailWithHostStreamError:

Shuts down the pinger object and tell the delegate about the error.

- (void)didFailWithHostStreamError:(CFStreamError)streamError

Parameters

streamError

Describes the failure.

Discussion

Shuts down the pinger object and tell the delegate about the error.

This converts the CFStreamError to an NSError and then call through to didFailWithError: to do the real work.

Declared In

FMPingFoundation.m

– pingPacketWithType:payload:requiresChecksum:

Builds a ping packet from the supplied parameters.

- (NSData *)pingPacketWithType:(uint8_t)type payload:(NSData *)payload requiresChecksum:(BOOL)requiresChecksum

Parameters

type

The packet type, which is different for IPv4 and IPv6.

payload

Data to place after the ICMP header.

requiresChecksum

Determines whether a checksum is calculated (IPv4) or not (IPv6).

Return Value

A ping packet suitable to be passed to the kernel.

Discussion

Builds a ping packet from the supplied parameters.

Declared In

FMPingFoundation.m

+ icmpHeaderOffsetInIPv4Packet:

Calculates the offset of the ICMP header within an IPv4 packet.

+ (NSUInteger)icmpHeaderOffsetInIPv4Packet:(NSData *)packet

Parameters

packet

The IPv4 packet, as returned to us by the kernel.

Return Value

The offset of the ICMP header, or NSNotFound.

Discussion

Calculates the offset of the ICMP header within an IPv4 packet.

In the IPv4 case the kernel returns us a buffer that includes the IPv4 header. We’re not interested in that, so we have to skip over it. This code does a rough check of the IPv4 header and, if it looks OK, returns the offset of the ICMP header.

Declared In

FMPingFoundation.m

– validateSequenceNumber:

Checks whether the specified sequence number is one we sent.

- (BOOL)validateSequenceNumber:(uint16_t)sequenceNumber

Parameters

sequenceNumber

The incoming sequence number.

Return Value

YES if the sequence number looks like one we sent.

Discussion

Checks whether the specified sequence number is one we sent.

Declared In

FMPingFoundation.m

– validatePing4ResponsePacket:sequenceNumber:

Checks whether an incoming IPv4 packet looks like a ping response.

- (BOOL)validatePing4ResponsePacket:(NSMutableData *)packet sequenceNumber:(uint16_t *)sequenceNumberPtr

Parameters

packet

The IPv4 packet, as returned to us by the kernel.

sequenceNumberPtr

A pointer to a place to start the ICMP sequence number.

Return Value

YES if the packet looks like a reasonable IPv4 ping response.

Discussion

Checks whether an incoming IPv4 packet looks like a ping response.

This routine modifies this packet data! It does this for two reasons:

  • It needs to zero out the checksum field of the ICMPHeader in order to do its checksum calculation.

  • It removes the IPv4 header from the front of the packet.

Declared In

FMPingFoundation.m

– validatePing6ResponsePacket:sequenceNumber:

Checks whether an incoming IPv6 packet looks like a ping response.

- (BOOL)validatePing6ResponsePacket:(NSMutableData *)packet sequenceNumber:(uint16_t *)sequenceNumberPtr

Parameters

packet

The IPv6 packet, as returned to us by the kernel; note that this routine could modify this data but does not need to in the IPv6 case.

sequenceNumberPtr

A pointer to a place to start the ICMP sequence number.

Return Value

YES if the packet looks like a reasonable IPv4 ping response.

Discussion

Checks whether an incoming IPv6 packet looks like a ping response.

Declared In

FMPingFoundation.m

– validatePingResponsePacket:sequenceNumber:

Checks whether an incoming packet looks like a ping response.

- (BOOL)validatePingResponsePacket:(NSMutableData *)packet sequenceNumber:(uint16_t *)sequenceNumberPtr

Parameters

packet

The packet, as returned to us by the kernel; note that may end up modifying this data.

sequenceNumberPtr

A pointer to a place to start the ICMP sequence number.

Return Value

YES if the packet looks like a reasonable IPv4 ping response.

Discussion

Checks whether an incoming packet looks like a ping response.

Declared In

FMPingFoundation.m

– readData

Reads data from the ICMP socket.

- (void)readData

Discussion

Reads data from the ICMP socket.

Called by the socket handling code (SocketReadCallback) to process an ICMP message waiting on the socket.

Declared In

FMPingFoundation.m

– startWithHostAddress

Starts the send and receive infrastructure.

- (void)startWithHostAddress

Discussion

Starts the send and receive infrastructure.

This is called once we’ve successfully resolved hostName in to hostAddress. It’s responsible for setting up the socket for sending and receiving pings.

Declared In

FMPingFoundation.m

– hostResolutionDone

Processes the results of our name-to-address resolution.

- (void)hostResolutionDone

Discussion

Processes the results of our name-to-address resolution.

Called by our CFHost resolution callback (HostResolveCallback) when host resolution is complete. We just latch the first appropriate address and kick off the send and receive infrastructure.

Declared In

FMPingFoundation.m

– start

The callback for our CFHost object.

- (void)start

Parameters

theHost

See the documentation for CFHostClientCallBack.

typeInfo

See the documentation for CFHostClientCallBack.

error

See the documentation for CFHostClientCallBack.

info

See the documentation for CFHostClientCallBack; this is actually a pointer to the ‘owning’ object.

Discussion

The callback for our CFHost object.

This simply routes the call to our hostResolutionDone or didFailWithHostStreamError: methods.

Declared In

FMPingFoundation.m

– stopHostResolution

Stops the name-to-address resolution infrastructure.

- (void)stopHostResolution

Discussion

Stops the name-to-address resolution infrastructure.

Declared In

FMPingFoundation.m

– stopSocket

Stops the send and receive infrastructure.

- (void)stopSocket

Discussion

Stops the send and receive infrastructure.

Declared In

FMPingFoundation.m

Other Methods

  hostName

A copy of the value passed to initWithHostName:.

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

Discussion

A copy of the value passed to initWithHostName:.

Declared In

FMPingFoundation.h

  delegate

The delegate for this object.

@property (nonatomic, weak, readwrite) id<FMPingFoundationDelegate> delegate

Discussion

The delegate for this object.

Delegate callbacks are schedule in the default run loop mode of the run loop of the thread that calls start.

Declared In

FMPingFoundation.h

  addressStyle

Controls the IP address version used by the object.

@property (nonatomic, assign, readwrite) FMPingFoundationAddressStyle addressStyle

Discussion

Controls the IP address version used by the object.

You should set this value before starting the object.

Declared In

FMPingFoundation.h

  hostAddress

The address being pinged.

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

Discussion

The address being pinged.

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 -pingFoundation:didStartWithAddress: is called.

Declared In

FMPingFoundation.h

  identifier

The identifier used by pings by this object.

@property (nonatomic, assign, readonly) uint16_t identifier

Discussion

The identifier used by pings by this object.

When you create an instance of this object it generates a random identifier that it uses to identify its own pings.

Declared In

FMPingFoundation.h

  nextSequenceNumber

The next sequence number to be used by this object.

@property (nonatomic, assign, readonly) uint16_t nextSequenceNumber

Discussion

The next sequence number to be used by this object.

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.

Declared In

FMPingFoundation.h

Extension Methods

  nextSequenceNumberHasWrapped

True if nextSequenceNumber has wrapped from 65535 to 0.

@property (nonatomic, assign, readwrite) BOOL nextSequenceNumberHasWrapped

Discussion

True if nextSequenceNumber has wrapped from 65535 to 0.

Declared In

FMPingFoundation.m

  host

A host object for name-to-address resolution.

@property (nonatomic, strong, readwrite, nullable) CFHostRef host

Discussion

A host object for name-to-address resolution.

Declared In

FMPingFoundation.m

  socket

A socket object for ICMP send and receive.

@property (nonatomic, strong, readwrite, nullable) CFSocketRef socket

Discussion

A socket object for ICMP send and receive.

Declared In

FMPingFoundation.m