5 // Created by Jens Alfke on 1/4/08.
6 // Copyright 2008 Jens Alfke. All rights reserved.
9 #import <Foundation/Foundation.h>
12 /** Represents an Internet Protocol address and port number (similar to a sockaddr_in).
13 IPAddress itself only remembers the raw 32-bit IPv4 address; the subclass HostAddress
14 also remembers the DNS host-name. */
15 @interface IPAddress : NSObject <NSCoding, NSCopying>
18 UInt32 _ipv4; // In network byte order (big-endian), just like struct in_addr
19 UInt16 _port; // native byte order
22 /** Initializes an IPAddress from a host name (which may be a DNS name or dotted-quad numeric form)
24 If the hostname is not in dotted-quad form, an instance of the subclass HostAddress will
25 be returned instead. */
26 - (id) initWithHostname: (NSString*)hostname port: (UInt16)port;
28 /** Creates an IPAddress from a host name (which may be a DNS name or dotted-quad numeric form)
30 If the hostname is not in dotted-quad form, an instance of the subclass HostAddress will
31 be returned instead. */
32 + (IPAddress*) addressWithHostname: (NSString*)hostname port: (UInt16)port;
34 /** Initializes an IPAddress from a raw IPv4 address (in network byte order, i.e. big-endian)
35 and port number (in native byte order) */
36 - (id) initWithIPv4: (UInt32)ipv4 port: (UInt16)port;
38 /** Initializes an IPAddress from a raw IPv4 address (in network byte order, i.e. big-endian).
39 The port number defaults to zero. */
40 - (id) initWithIPv4: (UInt32)ipv4;
42 /** Initializes an IPAddress from a BSD struct sockaddr. */
43 - (id) initWithSockAddr: (const struct sockaddr*)sockaddr;
45 /** Initializes an IPAddress from NSData containing a BSD struct sockaddr. */
46 - (id) initWithData: (NSData*)data;
48 /** Returns the IP address of this host (plus the specified port number).
49 If multiple network interfaces are active, the main one's address is returned. */
50 + (IPAddress*) localAddressWithPort: (UInt16)port;
52 /** Returns the IP address of this host (with a port number of zero).
53 If multiple network interfaces are active, the main one's address is returned. */
54 + (IPAddress*) localAddress;
56 /** Returns the address of the peer that an open socket is connected to.
57 (This calls getpeername.) */
58 + (IPAddress*) addressOfSocket: (CFSocketNativeHandle)socket;
60 /** Returns YES if the two objects have the same IP address, ignoring port numbers. */
61 - (BOOL) isSameHost: (IPAddress*)addr;
63 /** The raw IPv4 address, in network (big-endian) byte order. */
64 @property (readonly) UInt32 ipv4; // raw address in network byte order
66 /** The address as a dotted-quad string, e.g. @"10.0.1.1". */
67 @property (readonly) NSString* ipv4name;
69 /** The address as a DNS hostname or else a dotted-quad string.
70 (IPAddress itself always returns dotted-quad; HostAddress returns the hostname it was
72 @property (readonly) NSString* hostname; // dotted-quad string, or DNS name if I am a HostAddress
74 /** The port number, or zero if none was specified, in native byte order. */
75 @property (readonly) UInt16 port;
77 /** The address as an NSData object containing a struct sockaddr. */
78 @property (readonly) NSData* asData;
80 /** Is this IP address in a designated private/local address range, such as 10.0.1.X?
81 If so, the address is not globally meaningful outside of the local subnet. */
82 @property (readonly) BOOL isPrivate; // In a private/local addr range like 10.0.1.X?
87 /** A subclass of IPAddress that remembers the DNS hostname instead of a raw address.
88 An instance of HostAddress looks up its ipv4 address on the fly by calling gethostbyname. */
89 @interface HostAddress : IPAddress
95 - (id) initWithHostname: (NSString*)hostname port: (UInt16)port;
97 /** Initializes a HostAddress from a host name, plus a sockaddr struct and a port number.
98 (The port number overrides any port specified in the sockaddr struct.) */
99 - (id) initWithHostname: (NSString*)hostname
100 sockaddr: (const struct sockaddr*)sockaddr
107 /** An IPAddress that can keep track of statistics on when it was last sucessfully used
108 and the number of successful attempts. This is useful when keeping a cache of recent
109 addresses for a peer that doesn't have a stable address. */
110 @interface RecentAddress : IPAddress
113 CFAbsoluteTime _lastSuccess;
117 /** Initializes a RecentAddress from an IPAddress. (You can also initialize RecentAddress using
118 any inherited initializer method.) */
119 - (id) initWithIPAddress: (IPAddress*)addr;
121 /** The absolute time that -noteSuccess or -noteSeen was last called. */
122 @property (readonly) CFAbsoluteTime lastSuccess;
124 /** The number of times that -noteSuccess has been called. */
125 @property (readonly) UInt32 successes;
127 /** Call this to indicate that the address was successfully used to connect to the desired peer.
128 Returns YES if the state of the object has changed and it should be re-archived. */
129 - (BOOL) noteSuccess;
131 /** Call this to indicate that you have received evidence that this address is currently being
132 used by this peer. Unlike -noteSuccess it doesn't increment -successes, and only returns
133 YES (to indicate a persistent change) once every 18 hours (to avoid making the client
134 save its cache too often.) */