Zen API

- Home
- Help Topics
- Types by Category
- All Types
- Files

All Classes Files Functions Variables Typedefs Macros Groups Pages
kNetwork.h
Go to the documentation of this file.
1 /**
2 * @file kNetwork.h
3 * @brief IP networking definitions.
4 *
5 * @internal
6 * Copyright (C) 2008-2014 by LMI Technologies Inc.
7 * Licensed under the MIT License.
8 * Redistributed files must retain the above copyright notice.
9 */
10 #ifndef K_API_NETWORK_H
11 #define K_API_NETWORK_H
12
13 #include <kApi/kApiDef.h>
14
15 kBeginHeader()
16
17 /**
18 * @struct kIpVersion
19 * @extends kValue
20 * @ingroup kApi-Io
21 * @brief Internet Protocol version enumeration.
22 *
23 * The following enumerators are defined:
24 * - #kIP_VERSION_4
25 */
26 typedef k32s kIpVersion;
27
28 #define kIP_VERSION_4 (4) ///< Internet Protocol version 4.
29
30 /**
31 * @struct kIpAddress
32 * @extends kValue
33 * @ingroup kApi-Io
34 * @brief Represents an IP address.
35 */
36 typedef struct kIpAddress
37 {
38 kIpVersion version; ///< Address version.
39 kByte address[16]; ///< Address bytes (most significant byte first).
40 } kIpAddress;
41
42 /**
43 * Gets an address representing an automatically-assigned address.
44 *
45 * @public @memberof kIpAddress
46 * @param version IP version.
47 * @return Address value.
48 */
49 kFx(kIpAddress) kIpAddress_Any(kIpVersion version);
50
51 /**
52 * Gets an address representing an automatically-assigned IPv4 address.
53 *
54 * @public @memberof kIpAddress
55 * @return Address value.
56 */
57 kFx(kIpAddress) kIpAddress_AnyV4();
58
59 /**
60 * Gets an address suitable for broadcasting IPv4 datagrams.
61 *
62 * @public @memberof kIpAddress
63 * @return Address value.
64 */
65 kFx(kIpAddress) kIpAddress_BroadcastV4();
66
67 /**
68 * Gets the loopback address.
69 *
70 * @public @memberof kIpAddress
71 * @param version IP version.
72 * @return Address value.
73 */
74 kFx(kIpAddress) kIpAddress_Loopback(kIpVersion version);
75
76 /**
77 * Gets the IpV4 loopback address.
78 *
79 * @public @memberof kIpAddress
80 * @return Address value.
81 */
82 kFx(kIpAddress) kIpAddress_LoopbackV4();
83
84 /**
85 * Parses a text-formatted IP address.
86 *
87 * Supports dotted-quad (IPv4) format (e.g. "192.168.1.10").
88 *
89 * @public @memberof kIpAddress
90 * @param address Receives the IP address.
91 * @param text Text-formatted IP address.
92 * @return Operation status.
93 */
94 kFx(kStatus) kIpAddress_Parse(kIpAddress* address, const kChar* text);
95
96 /**
97 * Formats an IP address as a string.
98 *
99 * @public @memberof kIpAddress
100 * @param address IP address.
101 * @param text Receives formatted string.
102 * @param capacity Capacity of the string buffer.
103 * @return Operation status.
104 */
105 kFx(kStatus) kIpAddress_Format(kIpAddress address, kChar* text, kSize capacity);
106
107 /**
108 * Compares two addresses for equality.
109 *
110 * @public @memberof kIpAddress
111 * @param a First address.
112 * @param b Second address.
113 * @return kTRUE if addresses are equal; kFALSE otherwise.
114 */
115 kFx(kBool) kIpAddress_Equals(kIpAddress a, kIpAddress b);
116
117 /**
118 * Reports whether the given address is a loopback address.
119 *
120 * @public @memberof kIpAddress
121 * @param address IP address.
122 * @return kTRUE if the address is loopback; kFALSE otherwise.
123 */
124 kFx(kBool) kIpAddress_IsLoopback(kIpAddress address);
125
126 /**
127 * Converts an IPv4 address to a host-endian 32-bit integer.
128 *
129 * @public @memberof kIpAddress
130 * @param address IP address.
131 * @return Host-endian integer.
132 */
133 kFx(k32u) kIpAddress_ToHost32u(kIpAddress address);
134
135 /**
136 * Converts an IPv4 address to a network-endian 32-bit integer.
137 *
138 * @public @memberof kIpAddress
139 * @param address IP address.
140 * @return Network-endian integer.
141 */
142 kFx(k32u) kIpAddress_ToNet32u(kIpAddress address);
143
144 /**
145 * Converts a host-endian 32-bit integer to an IPv4 address.
146 *
147 * @public @memberof kIpAddress
148 * @param address Host-endian integer.
149 * @return IP address.
150 */
151 kFx(kIpAddress) kIpAddress_FromHost32u(k32u address);
152
153 /**
154 * Converts a network-endian 32-bit integer to an IPv4 address.
155 *
156 * @public @memberof kIpAddress
157 * @param address Network-endian integer.
158 * @return IP address.
159 */
160 kFx(kIpAddress) kIpAddress_FromNet32u(k32u address);
161
162 /**
163 * @struct kIpEndPoint
164 * @extends kValue
165 * @ingroup kApi-Io
166 * @brief Represents an IP end point (address, port).
167 *
168 * The following special ports are defined:
169 * - #kIP_PORT_ANY
170 */
171 typedef struct kIpEndPoint
172 {
173 kIpAddress address; ///< IP address.
174 k32u port; ///< Port number.
175 } kIpEndPoint; ///< Represents an IP end point.
176
177 #define kIP_PORT_ANY (0) ///< Used to request an automatically assigned port.
178
179 /**
180 * @struct kIpEntry
181 * @extends kValue
182 * @ingroup kApi-Io
183 * @brief Represents information about a local IP address.
184 */
185 typedef struct kIpEntry
186 {
187 kIpAddress address; ///< IP address.
188 kText128 name; ///< Host interface name.
189 } kIpEntry;
190
191 /**
192 * @class kNetwork
193 * @extends kObject
194 * @ingroup kApi-Io
195 * @brief A collection of static network utility methods.
196 */
197 typedef kObject kNetwork;
198
199 /**
200 * Determines the addresses associated with the specified host name.
201 *
202 * Only supports IPv4 addresses at this time.
203 *
204 * @public @memberof kNetwork
205 * @param name Host name, or kNULL for local host.
206 * @param addresses Receives addresses (kArrayList<kIpAddress>).
207 * @return Operation status.
208 */
209 kFx(kStatus) kNetwork_FindAddresses(const kChar* name, kArrayList addresses);
210
211 /**
212 * Finds information about local IP configuration.
213 *
214 * This function determines information pertaining to IP addresses on the local host.
215 * Some informational fields may be unavailable on some platforms.
216 *
217 * @private @memberof kNetwork
218 * @param entries Receives IP info (kArrayList<kIpEntry>).
219 * @return Operation status.
220 */
221 kFx(kStatus) kNetwork_FindEntries(kArrayList entries);
222
223 /**
224 * Determines the host name associated with the specified IP address.
225 *
226 * Only supports IPv4 addresses at this time.
227 *
228 * @public @memberof kNetwork
229 * @param address IP address.
230 * @param name Receives associated host name.
231 * @param capacity Capacity of the name argument.
232 * @return Operation status.
233 */
234 kFx(kStatus) kNetwork_FindName(kIpAddress address, kChar* name, kSize capacity);
235
236 kEndHeader()
237
238 #include <kApi/Io/kNetwork.x.h>
239
240 #endif
k32u
Represents a 32-bit unsigned integer.
kIpEndPoint::address
kIpAddress address
IP address.
Definition: kNetwork.h:173
kIpVersion
Internet Protocol version enumeration.
kIpAddress::kIpAddress_Format
kStatus kIpAddress_Format(kIpAddress address, kChar *text, kSize capacity)
Formats an IP address as a string.
kIpEndPoint::port
k32u port
Port number.
Definition: kNetwork.h:174
kIpAddress::kIpAddress_Any
kIpAddress kIpAddress_Any(kIpVersion version)
Gets an address representing an automatically-assigned address.
kIpAddress::kIpAddress_ToNet32u
k32u kIpAddress_ToNet32u(kIpAddress address)
Converts an IPv4 address to a network-endian 32-bit integer.
kIpAddress::kIpAddress_Equals
kBool kIpAddress_Equals(kIpAddress a, kIpAddress b)
Compares two addresses for equality.
kSize
Represents an unsigned integer that can store a pointer address.
kIpAddress::kIpAddress_FromNet32u
kIpAddress kIpAddress_FromNet32u(k32u address)
Converts a network-endian 32-bit integer to an IPv4 address.
kIpEntry::address
kIpAddress address
IP address.
Definition: kNetwork.h:187
kIpAddress
Represents an IP address.
Definition: kNetwork.h:36
kChar
Represents a single unit (byte) in a UTF-8 character.
kByte
Represents a byte on the current platform.
kIpAddress::kIpAddress_LoopbackV4
kIpAddress kIpAddress_LoopbackV4()
Gets the IpV4 loopback address.
kNetwork::kNetwork_FindName
kStatus kNetwork_FindName(kIpAddress address, kChar *name, kSize capacity)
Determines the host name associated with the specified IP address.
kIpAddress::kIpAddress_ToHost32u
k32u kIpAddress_ToHost32u(kIpAddress address)
Converts an IPv4 address to a host-endian 32-bit integer.
kIpAddress::kIpAddress_Loopback
kIpAddress kIpAddress_Loopback(kIpVersion version)
Gets the loopback address.
kIpAddress::kIpAddress_IsLoopback
kBool kIpAddress_IsLoopback(kIpAddress address)
Reports whether the given address is a loopback address.
kText128
Represents a 128-unit, null-terminated, kChar sequence.
kIpAddress::kIpAddress_BroadcastV4
kIpAddress kIpAddress_BroadcastV4()
Gets an address suitable for broadcasting IPv4 datagrams.
kNetwork::kNetwork_FindAddresses
kStatus kNetwork_FindAddresses(const kChar *name, kArrayList addresses)
Determines the addresses associated with the specified host name.
kApiDef.h
Essential API declarations.
k32s
Represents a 32-bit signed integer.
kIpAddress::kIpAddress_FromHost32u
kIpAddress kIpAddress_FromHost32u(k32u address)
Converts a host-endian 32-bit integer to an IPv4 address.
kIpAddress::version
kIpVersion version
Address version.
Definition: kNetwork.h:38
kIpEntry::name
kText128 name
Host interface name.
Definition: kNetwork.h:188
kArrayList
Represents a list implemented with a dynamic array.
kObject
Root of all class types in the Zen type system.
kNetwork
A collection of static network utility methods.
kStatus
Represents an enumeration of error codes.
kIpAddress::address
kByte address[16]
Address bytes (most significant byte first).
Definition: kNetwork.h:39
kIpEndPoint
Represents an IP end point (address, port).
Definition: kNetwork.h:171
kIpEntry
Represents information about a local IP address.
Definition: kNetwork.h:185
kBool
Represents a boolean value.
kIpAddress::kIpAddress_Parse
kStatus kIpAddress_Parse(kIpAddress *address, const kChar *text)
Parses a text-formatted IP address.
kIpAddress::kIpAddress_AnyV4
kIpAddress kIpAddress_AnyV4()
Gets an address representing an automatically-assigned IPv4 address.