Zen API

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

All Classes Files Functions Variables Typedefs Macros Groups Pages
kSocket.h
Go to the documentation of this file.
1 /**
2 * @file kSocket.h
3 * @brief Declares the kSocket class.
4 *
5 * @internal
6 * Copyright (C) 2004-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_SOCKET_H
11 #define K_API_SOCKET_H
12
13 #include <kApi/Io/kNetwork.h>
14
15 kBeginHeader()
16
17 /**
18 * @struct kSocketType
19 * @extends kValue
20 * @ingroup kApi-Io
21 * @brief Represents the underlying type of a socket.
22 *
23 * The following enumerators are defined:
24 * - #kSOCKET_TYPE_TCP
25 * - #kSOCKET_TYPE_UDP
26 */
27 typedef k32s kSocketType;
28
29 #define kSOCKET_TYPE_TCP (0) ///< TCP Socket.
30 #define kSOCKET_TYPE_UDP (1) ///< UDP Socket.
31
32 /**
33 * @struct kSocketEvent
34 * @ingroup kApi-Io
35 * @brief Represents an enumeration of socket event types.
36 *
37 * The following enumerators are defined:
38 * - #kSOCKET_EVENT_READ
39 * - #kSOCKET_EVENT_WRITE
40 * - #kSOCKET_EVENT_EXCEPT
41 */
42 typedef k32s kSocketEvent;
43
44 #define kSOCKET_EVENT_READ (1) ///< Socket ready for reading/accepting.
45 #define kSOCKET_EVENT_WRITE (2) ///< Socket potentially ready for writing.
46 #define kSOCKET_EVENT_EXCEPT (4) ///< Socket has an unexpected condition.
47
48 /**
49 * @class kSocket
50 * @extends kObject
51 * @ingroup kApi-Io
52 * @brief Represents a network socket.
53 */
54 //typedef kObject kSocket; --forward-declared in kApiDef.x.h
55
56 /**
57 * Waits until an event occurs on one or more sockets.
58 *
59 * Before calling this function, use kSocket_SetEvents to specify the events that the sockets
60 * should wait on. After calling this function, use the kSocket_Events function to determine
61 * which events have occurred.
62 *
63 * This function will return kERROR_TIMEOUT if no socket events occur by the end of the timeout period.
64 *
65 * @public @memberof kSocket
66 * @param sockets An array of sockets to wait on.
67 * @param count The number of sockets in the array.
68 * @param timeout Timeout, in microseconds.
69 * @return Operation status.
70 */
71 kFx(kStatus) kSocket_WaitAny(const kSocket* sockets, kSize count, k64u timeout);
72
73 /**
74 * Constructs a kSocket object.
75 *
76 * Note: Methods in the socket API are not thread-safe, unless otherwise noted.
77 *
78 * @public @memberof kSocket
79 * @param socket Destination for the constructed object handle.
80 * @param ipVersion Internet Protocol version.
81 * @param socketType The type of socket to create (i.e. TCP or UDP).
82 * @param allocator Memory allocator (or kNULL for default).
83 * @return Operation status.
84 */
85 kFx(kStatus) kSocket_Construct(kSocket* socket, kIpVersion ipVersion, kSocketType socketType, kAlloc allocator);
86
87 /**
88 * Binds the socket to a local IP address and/or port.
89 *
90 * @public @memberof kSocket
91 * @param socket Destination for the constructed object handle.
92 * @param address A local IP address, or kIpAddress_Any().
93 * @param port A local port number, or kIP_PORT_ANY.
94 * @return Operation status.
95 */
96 kFx(kStatus) kSocket_Bind(kSocket socket, kIpAddress address, k32u port);
97
98 /**
99 * Connects the socket to a remote end point.
100 *
101 * A connection can be attempted only once per socket object.
102 *
103 * @public @memberof kSocket
104 * @param socket Socket object.
105 * @param address The remote IP address.
106 * @param port The remote port number.
107 * @param timeout The timeout interval, in microseconds.
108 * @return Operation status.
109 */
110 kFx(kStatus) kSocket_Connect(kSocket socket, kIpAddress address, k32u port, k64u timeout);
111
112 /**
113 * Places the socket into a listening state, to monitor for incoming connection requests.
114 *
115 * @public @memberof kSocket
116 * @param socket Socket object.
117 * @param backlog The maximum number of pending connection requests to enqueue.
118 * @return Operation status.
119 */
120 kFx(kStatus) kSocket_Listen(kSocket socket, kSize backlog);
121
122 /**
123 * Blocks until an incoming connection request is accepted.
124 *
125 * @public @memberof kSocket
126 * @param socket A socket object in the listening state.
127 * @param connection Receives a socket object representing the newly-established connection, or kNULL.
128 * @param allocator Memory allocator (or kNULL for default).
129 * @return Operation status.
130 */
131 kFx(kStatus) kSocket_Accept(kSocket socket, kSocket* connection, kAlloc allocator);
132
133 /**
134 * Waits for a socket event.
135 *
136 * Before calling this function, use kSocket_SetEvents to specify the events that the socket
137 * should wait on. After calling this function, use the kSocket_Events function to determine
138 * which events have occurred.
139 *
140 * This function will return kERROR_TIMEOUT if no events occur by the end of the timeout period.
141 *
142 * @public @memberof kSocket
143 * @param socket Socket object.
144 * @param timeout Timeout, in microseconds.
145 * @return Operation status.
146 */
147 kFx(kStatus) kSocket_Wait(kSocket socket, k64u timeout);
148
149 /**
150 * Reads one or more bytes.
151 *
152 * In blocking mode, this function will block until at least one byte is received (or a read timeout occurs).
153 *
154 * In non-blocking mode, this function will read at least one byte. kSocket_Wait should be used to determine
155 * when this function can be called successfully.
156 *
157 * If the socket was closed by the remote peer, this function will return kERROR_CLOSED.
158 *
159 * @public @memberof kSocket
160 * @param socket Socket object.
161 * @param buffer Buffer to receive bytes.
162 * @param size The maximum number of bytes to read.
163 * @param read The number of bytes that were read.
164 * @return Operation status.
165 */
166 kFx(kStatus) kSocket_Read(kSocket socket, void* buffer, kSize size, kSize* read);
167
168 /**
169 * Reads a datagram.
170 *
171 * In blocking mode, this function will block until a datagram is read (or a read timeout occurs).
172 *
173 * In non-blocking mode, kSocket_Wait should be used to determine when this function can be called successfully.
174 *
175 * @public @memberof kSocket
176 * @param socket Socket object.
177 * @param endPoint The address of the sender.
178 * @param buffer Buffer to receive the datagram.
179 * @param size The maximum number of bytes to return.
180 * @param read The number of bytes that were read.
181 * @return Operation status.
182 */
183 kFx(kStatus) kSocket_ReadFrom(kSocket socket, kIpEndPoint *endPoint, void* buffer, kSize size, kSize* read);
184
185 /**
186 * Writes one or more bytes.
187 *
188 * In blocking mode, this function will block until all bytes are written (or a write timeout occurs).
189 *
190 * In non-blocking mode, this function will write zero or more bytes. kSocket_Wait can be used to
191 * determine when buffer space is available for a write operation, increasing the odds that bytes
192 * can be written successfully.
193 *
194 * @public @memberof kSocket
195 * @param socket Socket object.
196 * @param buffer Buffer of bytes to write.
197 * @param size The number of bytes to write.
198 * @param written The number of bytes that were written.
199 * @return Operation status.
200 */
201 kFx(kStatus) kSocket_Write(kSocket socket, const void* buffer, kSize size, kSize* written);
202
203 /**
204 * Sends a datagram.
205 *
206 * In blocking mode, this function will block until the datagram is sent (or a write timeout occurs).
207 *
208 * In non-blocking mode, use kSocket_Wait to determine when this function can be called successfully.
209 *
210 * @public @memberof kSocket
211 * @param socket Socket object.
212 * @param address IP address of the recipient.
213 * @param port Port number of the recipient.
214 * @param buffer Buffer containing the datagram to send.
215 * @param size The number of bytes in the supplied buffer.
216 * @return Operation status.
217 */
218 kFx(kStatus) kSocket_WriteTo(kSocket socket, kIpAddress address, k32u port, const void* buffer, kSize size);
219
220 /**
221 * Sets the event types that a socket will wait on.
222 *
223 * By default, sockets wait on read events.
224 *
225 * @public @memberof kSocket
226 * @param socket Socket object.
227 * @param events One or more event types to wait on.
228 * @return Operation status.
229 */
230 kFx(kStatus) kSocket_SetEvents(kSocket socket, kSocketEvent events);
231
232 /**
233 * Gets the events detected during the most recent wait operation.
234 *
235 * @public @memberof kSocket
236 * @param socket Socket object.
237 * @return Detected events.
238 */
239 kFx(kSocketEvent) kSocket_Events(kSocket socket);
240
241 /**
242 * Determines whether the socket will block on read/write requests.
243 *
244 * By default, sockets are created in blocking mode.
245 *
246 * @public @memberof kSocket
247 * @param socket Socket object.
248 * @param isBlocking If kTRUE, the socket will be placed in blocking mode.
249 * @return Operation status.
250 */
251 kFx(kStatus) kSocket_SetBlocking(kSocket socket, kBool isBlocking);
252
253 /**
254 * Sets the size of the write buffer used by the underlying operating system.
255 *
256 * @public @memberof kSocket
257 * @param socket Socket object.
258 * @param size Size of the write buffer.
259 * @return Operation status.
260 */
261 kFx(kStatus) kSocket_SetWriteBuffer(kSocket socket, kSize size);
262
263 /**
264 * Sets the size of the read buffer used by the underlying operating system.
265 *
266 * @public @memberof kSocket
267 * @param socket Socket object.
268 * @param size Size of the read buffer.
269 * @return Operation status.
270 */
271 kFx(kStatus) kSocket_SetReadBuffer(kSocket socket, kSize size);
272
273 /**
274 * Sets the timeout duration for blocking write operations.
275 *
276 * By default, socket objects do not use a timeout interval and can block indefinitely.
277 *
278 * @public @memberof kSocket
279 * @param socket Socket object.
280 * @param timeout Timeout value, in microseconds.
281 * @return Operation status.
282 */
283 kFx(kStatus) kSocket_SetWriteTimeout(kSocket socket, k64u timeout);
284
285 /**
286 * Sets the timeout duration for blocking read operations.
287 *
288 * By default, kSocket objects do not use a timeout interval and can block indefinitely.
289 *
290 * @public @memberof kSocket
291 * @param socket Socket object.
292 * @param timeout Timeout value, in microseconds.
293 * @return Operation status.
294 */
295 kFx(kStatus) kSocket_SetReadTimeout(kSocket socket, k64u timeout);
296
297 /**
298 * Enables or disables datagram broadcasting.
299 *
300 * This function is typically used in conjunction with a UDP socket that is bound
301 * to a local address. Sending to kIpAddress_BroacastV4() will broadcast a
302 * datagram on the subnet associated with the bound IPv4 address.
303 *
304 * @public @memberof kSocket
305 * @param socket Socket object.
306 * @param broadcast kTRUE to enable broadcasts; kFALSE otherwise.
307 * @return Operation status.
308 */
309 kFx(kStatus) kSocket_EnableBroadcast(kSocket socket, kBool broadcast);
310
311 /**
312 * Enables or disables reuse of a local end point within a short period of time.
313 *
314 * The option is typically used to allow a server to rebind to a local end point
315 * while a previous socket with the same local end point is in the TIME_WAIT state.
316 * This can be useful when a server must be stopped and started within a brief interval,
317 * but there is a small risk that packets with identical source/destination information
318 * could be misdirected to the new socket.
319 *
320 * @public @memberof kSocket
321 * @param socket Socket object.
322 * @param reuse kTRUE to enable reuse of IP addresses; kFALSE otherwise.
323 * @return Operation status.
324 */
325 kFx(kStatus) kSocket_EnableReuseAddress(kSocket socket, kBool reuse);
326
327 /**
328 * Can be used to disable the Nagle algorithm.
329 *
330 * The Nagle algorithm is enabled by default. When enabled, small segments of outbound
331 * data are coalesced over a brief time period in order to improve network efficiency.
332 *
333 * @public @memberof kSocket
334 * @param socket Socket object.
335 * @param noDelay kTRUE to disable the Nagle algorithm; kFALSE to enable.
336 * @return Operation status.
337 */
338 kFx(kStatus) kSocket_SetNoDelay(kSocket socket, kBool noDelay);
339
340 /**
341 * Specifies the duration that a TCP connection can remain open when the socket is closed
342 * in order to ensure that all outbound bytes are transmitted to the receiver.
343 *
344 * If the linger time is not set, then a default linger time will be selected by
345 * the underlying operating system.
346 *
347 * @public @memberof kSocket
348 * @param socket Socket object.
349 * @param lingerTime Linger time, in microseconds (0 for immediate closure).
350 * @return Operation status.
351 */
352 kFx(kStatus) kSocket_SetLingerTime(kSocket socket, k64u lingerTime);
353
354 /**
355 * Binds the socket to a specific network interface.
356 *
357 * This function was introduced to work around a UDP broadcast issue on QNX, and is not
358 * supported on all platforms.
359 *
360 * @public @memberof kSocket
361 * @param socket Socket object.
362 * @param interfaceName Device name.
363 * @return Operation status.
364 */
365 kFx(kStatus) kSocket_BindToDevice(kSocket socket, const kChar* interfaceName);
366
367 /**
368 * Returns the local end point for a bound socket.
369 *
370 * @public @memberof kSocket
371 * @param socket Socket object.
372 * @param endPoint Local end point.
373 * @return Operation status.
374 */
375 kFx(kStatus) kSocket_LocalEndPoint(kSocket socket, kIpEndPoint* endPoint);
376
377 /**
378 * Returns the remote end point for a connected socket.
379 *
380 * @public @memberof kSocket
381 * @param socket Socket object.
382 * @param endPoint Remote end point.
383 * @return Operation status.
384 */
385 kFx(kStatus) kSocket_RemoteEndPoint(kSocket socket, kIpEndPoint* endPoint);
386
387 /**
388 * Reports any internal errors that will prevent success of future communication attempts.
389 *
390 * @public @memberof kSocket
391 * @param socket Socket object.
392 * @return Socket status.
393 */
394 kFx(kStatus) kSocket_Status(kSocket socket);
395
396 kEndHeader()
397
398 #include <kApi/Io/kSocket.x.h>
399
400 #endif
k32u
Represents a 32-bit unsigned integer.
kSocket::kSocket_SetReadBuffer
kStatus kSocket_SetReadBuffer(kSocket socket, kSize size)
Sets the size of the read buffer used by the underlying operating system.
kSocket::kSocket_Connect
kStatus kSocket_Connect(kSocket socket, kIpAddress address, k32u port, k64u timeout)
Connects the socket to a remote end point.
kSocket::kSocket_RemoteEndPoint
kStatus kSocket_RemoteEndPoint(kSocket socket, kIpEndPoint *endPoint)
Returns the remote end point for a connected socket.
kSocket::kSocket_SetNoDelay
kStatus kSocket_SetNoDelay(kSocket socket, kBool noDelay)
Can be used to disable the Nagle algorithm.
k64u
Represents a 64-bit unsigned integer.
kIpVersion
Internet Protocol version enumeration.
kSocket::kSocket_BindToDevice
kStatus kSocket_BindToDevice(kSocket socket, const kChar *interfaceName)
Binds the socket to a specific network interface.
kSocket::kSocket_ReadFrom
kStatus kSocket_ReadFrom(kSocket socket, kIpEndPoint *endPoint, void *buffer, kSize size, kSize *read)
Reads a datagram.
kSocket::kSocket_Status
kStatus kSocket_Status(kSocket socket)
Reports any internal errors that will prevent success of future communication attempts.
kSize
Represents an unsigned integer that can store a pointer address.
kAlloc
Abstract base class for memory allocator types.
kSocketEvent
Represents an enumeration of socket event types.
kSocket::kSocket_SetBlocking
kStatus kSocket_SetBlocking(kSocket socket, kBool isBlocking)
Determines whether the socket will block on read/write requests.
kIpAddress
Represents an IP address.
Definition: kNetwork.h:36
kSocket::kSocket_Construct
kStatus kSocket_Construct(kSocket *socket, kIpVersion ipVersion, kSocketType socketType, kAlloc allocator)
Constructs a kSocket object.
kChar
Represents a single unit (byte) in a UTF-8 character.
kSocket::kSocket_EnableReuseAddress
kStatus kSocket_EnableReuseAddress(kSocket socket, kBool reuse)
Enables or disables reuse of a local end point within a short period of time.
kSocket::kSocket_Write
kStatus kSocket_Write(kSocket socket, const void *buffer, kSize size, kSize *written)
Writes one or more bytes.
kSocket::kSocket_Bind
kStatus kSocket_Bind(kSocket socket, kIpAddress address, k32u port)
Binds the socket to a local IP address and/or port.
kSocket::kSocket_Wait
kStatus kSocket_Wait(kSocket socket, k64u timeout)
Waits for a socket event.
kSocket::kSocket_SetWriteBuffer
kStatus kSocket_SetWriteBuffer(kSocket socket, kSize size)
Sets the size of the write buffer used by the underlying operating system.
kSocket::kSocket_Accept
kStatus kSocket_Accept(kSocket socket, kSocket *connection, kAlloc allocator)
Blocks until an incoming connection request is accepted.
kSocketType
Represents the underlying type of a socket.
kSocket::kSocket_SetWriteTimeout
kStatus kSocket_SetWriteTimeout(kSocket socket, k64u timeout)
Sets the timeout duration for blocking write operations.
kSocket::kSocket_Read
kStatus kSocket_Read(kSocket socket, void *buffer, kSize size, kSize *read)
Reads one or more bytes.
k32s
Represents a 32-bit signed integer.
kSocket::kSocket_WaitAny
kStatus kSocket_WaitAny(const kSocket *sockets, kSize count, k64u timeout)
Waits until an event occurs on one or more sockets.
kSocket::kSocket_LocalEndPoint
kStatus kSocket_LocalEndPoint(kSocket socket, kIpEndPoint *endPoint)
Returns the local end point for a bound socket.
kSocket::kSocket_Events
kSocketEvent kSocket_Events(kSocket socket)
Gets the events detected during the most recent wait operation.
kSocket::kSocket_EnableBroadcast
kStatus kSocket_EnableBroadcast(kSocket socket, kBool broadcast)
Enables or disables datagram broadcasting.
kSocket::kSocket_SetReadTimeout
kStatus kSocket_SetReadTimeout(kSocket socket, k64u timeout)
Sets the timeout duration for blocking read operations.
kNetwork.h
IP networking definitions.
kSocket::kSocket_Listen
kStatus kSocket_Listen(kSocket socket, kSize backlog)
Places the socket into a listening state, to monitor for incoming connection requests.
kSocket::kSocket_WriteTo
kStatus kSocket_WriteTo(kSocket socket, kIpAddress address, k32u port, const void *buffer, kSize size)
Sends a datagram.
kStatus
Represents an enumeration of error codes.
kIpEndPoint
Represents an IP end point (address, port).
Definition: kNetwork.h:171
kSocket::kSocket_SetLingerTime
kStatus kSocket_SetLingerTime(kSocket socket, k64u lingerTime)
Specifies the duration that a TCP connection can remain open when the socket is closed in order to en...
kSocket::kSocket_SetEvents
kStatus kSocket_SetEvents(kSocket socket, kSocketEvent events)
Sets the event types that a socket will wait on.
kSocket
Represents a network socket.
kBool
Represents a boolean value.