Zen API

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

All Classes Files Functions Variables Typedefs Macros Groups Pages
kUdpClient.h
Go to the documentation of this file.
1 /**
2 * @file kUdpClient.h
3 * @brief Declares the kUdpClient class.
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_UDP_CLIENT_H
11 #define K_API_UDP_CLIENT_H
12
13 #include <kApi/Io/kNetwork.h>
14
15 kBeginHeader()
16
17 /**
18 * @class kUdpClient
19 * @extends kStream
20 * @ingroup kApi-Io
21 * @brief Represents a UDP client.
22 */
23 //typedef kStream kUdpClient; --forward-declared in kApiDef.x.h
24
25 /**
26 * Constructs a UDP client object.
27 *
28 * @public @memberof kUdpClient
29 * @param client Destination for the constructed object handle.
30 * @param ipVersion Internet Protocol version.
31 * @param allocator Memory allocator (or kNULL for default).
32 * @return Operation status.
33 */
34 kFx(kStatus) kUdpClient_Construct(kUdpClient* client, kIpVersion ipVersion, kAlloc allocator);
35
36 /**
37 * Binds the client to a local IP address and/or port.
38 *
39 * @public @memberof kUdpClient
40 * @param client UDP client object.
41 * @param address A local IP address, or kIpAddress_Any().
42 * @param port A local port number, or kIP_PORT_ANY.
43 * @return Operation status.
44 */
45 kFx(kStatus) kUdpClient_Bind(kUdpClient client, kIpAddress address, k32u port);
46
47 /**
48 * Blocks until a datagram is received into the provided buffer (or until a timeout occurs).
49 *
50 * This method can be used when read buffering is disabled to read a datagram directly from the
51 * underlying socket.
52 *
53 * @public @memberof kUdpClient
54 * @param client UDP client object.
55 * @param endPoint Receives the end point of the sender.
56 * @param buffer Destination for received bytes.
57 * @param capacity Maximum count of bytes to read.
58 * @param received Receives the size of the received datagram.
59 * @param timeout Timeout, in microseconds.
60 * @return Operation status.
61 */
62 kFx(kStatus) kUdpClient_ReadFrom(kUdpClient client, kIpEndPoint* endPoint, void* buffer, kSize capacity, kSize* received, k64u timeout);
63
64 /**
65 * Blocks until the provided datagram is written to the underlying socket (or until a timeout occurs).
66 *
67 * This method can be used when write buffering is disabled to write a datagram directly to the
68 * underlying socket.
69 *
70 * @public @memberof kUdpClient
71 * @param client UDP client object.
72 * @param buffer Bytes to be written.
73 * @param size Count of bytes to be written.
74 * @param address IP address of the recipient.
75 * @param port Port number of the recipient.
76 * @param timeout Timeout, in microseconds.
77 * @return Operation status.
78 */
79 kFx(kStatus) kUdpClient_WriteTo(kUdpClient client, const void* buffer, kSize size, kIpAddress address, k32u port, k64u timeout);
80
81 /**
82 * Blocks until a datagram is received into kUdpClient's read buffer (or until a timeout occurs).
83 *
84 * The Receive method is used to receive a datagram into kUdpClient's internal read buffer.
85 * Once the datagram has been received, the kStream_Read method can be used to read out the
86 * datagram.
87 *
88 * @public @memberof kUdpClient
89 * @param client UDP client object.
90 * @param endPoint Receives the end point of the sender.
91 * @param received Receives the size of the received datagram.
92 * @param timeout Timeout, in microseconds.
93 * @return Operation status.
94 */
95 kFx(kStatus) kUdpClient_Receive(kUdpClient client, kIpEndPoint* endPoint, kSize* received, k64u timeout);
96
97 /**
98 * Blocks until the datagram in kUdpClient's internal write buffer is written to the underlying socket
99 * (or until a timeout occurs).
100 *
101 * The Send method is used to send a datagram that has been written into kUdpClient's internal
102 * write buffer. Bytes are written into kUdpClient's internal buffer via the kStream_Write method.
103 *
104 * Optionally the internal write buffer is updated. User clear=kFALSE in case retransmission is
105 * needed.
106 *
107 * @public @memberof kUdpClient
108 * @param client UDP client object.
109 * @param address IP address of the recipient.
110 * @param port Port number of the recipient.
111 * @param timeout Timeout, in microseconds.
112 * @param clear Specifies whether the internal write buffer pointer is updated.
113 * @return Operation status.
114 */
115 kFx(kStatus) kUdpClient_Send(kUdpClient client, kIpAddress address, k32u port, k64u timeout, kBool clear);
116
117 /**
118 * Clears the internal write buffer state.
119 * @public @memberof kUdpClient
120 * @param client UDP client object.
121 * @return Operation status.
122 */
123 kFx(kStatus) kUdpClient_Clear(kUdpClient client);
124
125 /**
126 * Enables or disables broadcasting.
127 *
128 * If broadcasting is enabled, sending to kIpAddress_BroadcastV4() will broadcast a datagram
129 * on the subnet associated with the IPv4 address to which the client is bound.
130 *
131 * Broadcasts are disabled by default.
132 *
133 * @public @memberof kUdpClient
134 * @param client UDP client object.
135 * @param broadcast kTRUE to enable broadcasts; kFALSE otherwise.
136 * @return Operation status.
137 */
138 kFx(kStatus) kUdpClient_EnableBroadcast(kUdpClient client, kBool broadcast);
139
140 /**
141 * Enables the ability to receive broadcast messages.
142 *
143 * This function is required to work around a limitation in DSP/BIOS that prevents sockets
144 * from receiving broadcasts unless they are bound to kIpAddress_AnyV4(). When used, this
145 * function must be called before kUdpClient_Bind.
146 *
147 * This function is harmless (no effect) when used on other operating systems.
148 *
149 * @public @memberof kUdpClient
150 * @param client UDP client object.
151 * @param broadcast kTRUE to enable broadcasts; kFALSE otherwise.
152 * @return Operation status.
153 */
154 kFx(kStatus) kUdpClient_EnableBroadcastReceive(kUdpClient client, kBool broadcast);
155
156 /**
157 * Enables or disables reuse of a local end point within a short period of time.
158 *
159 * The option is typically used to allow a server to rebind to a local end point
160 * while a previous socket with the same local end point is in the TIME_WAIT state.
161 * This can be useful when a server must be stopped and started within a brief interval,
162 * but there is a small risk that packets with identical source/destination information
163 * could be misdirected to the new socket.
164 *
165 * This option is disabled by default.
166 *
167 * @public @memberof kUdpClient
168 * @param client UDP client object.
169 * @param reuse kTRUE to enable reuse of IP addresses; kFALSE otherwise.
170 * @return Operation status.
171 */
172 kFx(kStatus) kUdpClient_EnableReuseAddress(kUdpClient client, kBool reuse);
173
174 /**
175 * Sets the size of write buffers.
176 *
177 * Socket buffers decouple the sender and receiver, so that the sender does not need to block
178 * while waiting for the receiver to receive all bytes. Client buffers enable the sender to
179 * formulate a datagram over multiple writes, rather than supplying the entire datagram in
180 * a single write call.
181 *
182 * If the client buffer size is greater than zero, use the kUdpClient_Send method to
183 * send the datagram when writing is complete. If the client buffer size is zero, a datagram
184 * can be sent immediately (without buffering) using kUdpClient_WriteTo.
185 *
186 * By default, the client buffer size is zero and the socket buffer size is determined by the
187 * underlying operating system.
188 *
189 * @public @memberof kUdpClient
190 * @param client UDP client object.
191 * @param socketSize Size of the write buffer maintained by the underlying socket (-1 to leave unchanged).
192 * @param clientSize Size of the write buffer maintained by the client object (-1 to leave unchanged).
193 * @return Operation status.
194 */
195 kFx(kStatus) kUdpClient_SetWriteBuffers(kUdpClient client, kSSize socketSize, kSSize clientSize);
196
197 /**
198 * Sets the size of read buffers.
199 *
200 * Socket buffers decouple the sender and receiver, so that the sender does not need to block
201 * while waiting for the receiver to receive all bytes. Client buffers enable the client to read
202 * the datagram over multiple read calls, rather than receiving the entire datagram in a single read
203 * call.
204 *
205 * If the client buffer size is greater than zero, use the kUdpClient_Receive method to
206 * receive a datagram before calling kUdpClient_Read. If the client buffer size is zero, a
207 * complete datagram can be received (without buffering) using kUdpClient_ReadFrom.
208 *
209 * @public @memberof kUdpClient
210 * @param client UDP client object.
211 * @param socketSize Size of the read buffer maintained by the underlying socket (-1 to leave unchanged).
212 * @param clientSize Size of the read buffer maintained by the client object (-1 to leave unchanged).
213 * @return Operation status.
214 */
215 kFx(kStatus) kUdpClient_SetReadBuffers(kUdpClient client, kSSize socketSize, kSSize clientSize);
216
217 /**
218 * Returns the underlying kSocket object.
219 *
220 * @public @memberof kUdpClient
221 * @param client UDP client object.
222 * @return Socket object.
223 */
224 kFx(kSocket) kUdpClient_Socket(kUdpClient client);
225
226 /**
227 * Returns the local end point for a bound client.
228 *
229 * @public @memberof kUdpClient
230 * @param client UDP client object.
231 * @param endPoint Local end point.
232 * @return Socket object.
233 */
234 kFx(kStatus) kUdpClient_LocalEndPoint(kUdpClient client, kIpEndPoint* endPoint);
235
236 kEndHeader()
237
238 #include <kApi/Io/kUdpClient.x.h>
239
240 #endif
kUdpClient::kUdpClient_Send
kStatus kUdpClient_Send(kUdpClient client, kIpAddress address, k32u port, k64u timeout, kBool clear)
Blocks until the datagram in kUdpClient's internal write buffer is written to the underlying socket (...
k32u
Represents a 32-bit unsigned integer.
k64u
Represents a 64-bit unsigned integer.
kIpVersion
Internet Protocol version enumeration.
kUdpClient::kUdpClient_SetReadBuffers
kStatus kUdpClient_SetReadBuffers(kUdpClient client, kSSize socketSize, kSSize clientSize)
Sets the size of read buffers.
kUdpClient::kUdpClient_EnableBroadcastReceive
kStatus kUdpClient_EnableBroadcastReceive(kUdpClient client, kBool broadcast)
Enables the ability to receive broadcast messages.
kSize
Represents an unsigned integer that can store a pointer address.
kAlloc
Abstract base class for memory allocator types.
kUdpClient::kUdpClient_Clear
kStatus kUdpClient_Clear(kUdpClient client)
Clears the internal write buffer state.
kUdpClient::kUdpClient_LocalEndPoint
kStatus kUdpClient_LocalEndPoint(kUdpClient client, kIpEndPoint *endPoint)
Returns the local end point for a bound client.
kIpAddress
Represents an IP address.
Definition: kNetwork.h:36
kSSize
Represents a signed integer that can store a pointer address.
kUdpClient::kUdpClient_EnableBroadcast
kStatus kUdpClient_EnableBroadcast(kUdpClient client, kBool broadcast)
Enables or disables broadcasting.
kUdpClient::kUdpClient_ReadFrom
kStatus kUdpClient_ReadFrom(kUdpClient client, kIpEndPoint *endPoint, void *buffer, kSize capacity, kSize *received, k64u timeout)
Blocks until a datagram is received into the provided buffer (or until a timeout occurs).
kUdpClient
Represents a UDP client.
kUdpClient::kUdpClient_WriteTo
kStatus kUdpClient_WriteTo(kUdpClient client, const void *buffer, kSize size, kIpAddress address, k32u port, k64u timeout)
Blocks until the provided datagram is written to the underlying socket (or until a timeout occurs)...
kUdpClient::kUdpClient_Bind
kStatus kUdpClient_Bind(kUdpClient client, kIpAddress address, k32u port)
Binds the client to a local IP address and/or port.
kUdpClient::kUdpClient_Socket
kSocket kUdpClient_Socket(kUdpClient client)
Returns the underlying kSocket object.
kNetwork.h
IP networking definitions.
kUdpClient::kUdpClient_Construct
kStatus kUdpClient_Construct(kUdpClient *client, kIpVersion ipVersion, kAlloc allocator)
Constructs a UDP client object.
kStatus
Represents an enumeration of error codes.
kIpEndPoint
Represents an IP end point (address, port).
Definition: kNetwork.h:171
kUdpClient::kUdpClient_Receive
kStatus kUdpClient_Receive(kUdpClient client, kIpEndPoint *endPoint, kSize *received, k64u timeout)
Blocks until a datagram is received into kUdpClient's read buffer (or until a timeout occurs)...
kUdpClient::kUdpClient_EnableReuseAddress
kStatus kUdpClient_EnableReuseAddress(kUdpClient client, kBool reuse)
Enables or disables reuse of a local end point within a short period of time.
kUdpClient::kUdpClient_SetWriteBuffers
kStatus kUdpClient_SetWriteBuffers(kUdpClient client, kSSize socketSize, kSSize clientSize)
Sets the size of write buffers.
kSocket
Represents a network socket.
kBool
Represents a boolean value.