FreeCalypso > hg > fc-selenite

comparison src/g23m-fad/tcpip/rnet/rnet_rt/rnet_rt_api.h @ 1:d393cd9bb723

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
src/g23m-*: initial import from Magnetite
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 15 Jul 2018 04:40:46 +0000
parents
children
comparison
equal deleted inserted replaced
0:b6a5e36de839 1:d393cd9bb723
1 /**
2 * @file rnet_rt_api.h
3 *
4 * API Definition for RNET_RT SWE.
5 *
6 * @author Jose Yp-Tcha (j-yp-tcha@ti.com)
7 * @version 0.1
8 */
9
10 /*
11 * $Id: rnet_rt_api.h,v 1.5 2002/10/30 15:23:34 rf Exp $
12 * $Name: ti_20021030 $
13 *
14 * History:
15 *
16 * Date Author Modification
17 * -------------------------------------------------------------------
18 * 3/19/2002 Jose Yp-Tcha (j-yp-tcha@ti.com) Create.
19 * 4/3/2002 Regis Feneon ngip api
20 *
21 * (C) Copyright 2002 by TI, All Rights Reserved
22 */
23
24 #include "rnet_cfg.h"
25
26 #ifdef RNET_CFG_REAL_TRANSPORT
27
28 #ifndef __RNET_RT_API_H_
29 #define __RNET_RT_API_H_
30
31 #include "rvm_gen.h" /* Generic RVM types and functions. */
32 #include "rnet_api.h"
33
34 #ifdef __cplusplus
35 extern "C"
36 {
37 #endif
38
39 /**
40 * @name RNET_RT Return type and return values.
41 *
42 * Currently they are the standard RV return types, but they may
43 * be customized in the future.
44 */
45 /*@{*/
46
47 #define RNET_RT_OK RV_OK
48 #define RNET_RT_NOT_SUPPORTED RV_NOT_SUPPORTED
49 #define RNET_RT_MEMORY_ERR RV_MEMORY_ERR
50 #define RNET_RT_INTERNAL_ERR RV_INTERNAL_ERR
51 /*@}*/
52
53 /**
54 * @name API functions
55 *
56 * API functions declarations (bridge functions).
57 */
58 /*@{*/
59
60 /**
61 * Creates a new connection identifier (T_RNET_DESC).
62 *
63 * The connection ID is not active until it has either been bound
64 * to a local address or connected to a remote address.
65 *
66 * @param proto Protocol that should be used [IN].
67 * @param desc Connection identifier created [OUT].
68 * @param return_path Return path that should be used to send
69 * the messages like accept, connect, etc [IN].
70 * @return RNET_MEMORY_ERR No available memory to create the new connection id.
71 * RNET_NOT_INITIALIZED NET subsystem not initialized (internal error).
72 * RNET_INTERNAL_ERR Network subsystem failed.
73 * or No more socket descriptors available.
74 * RNET_NOT_READY Still processing a callback function.
75 * RNET_NOT_SUPPORTED Specified protocol not supported.
76 * RNET_OK Connection ID successfully created.
77 */
78 T_RNET_RET rnet_rt_new ( T_RNET_IPPROTO proto,
79 T_RNET_DESC ** desc,
80 T_RV_RETURN_PATH return_path);
81
82 /**
83 * Binds the connection to a local IP address and port number.
84 *
85 * @param desc Connection identifier [IN].
86 * @param local_addr Local IP address
87 * The IP address can be specified as RNET_IP_ADDR_ANY
88 * in order to bind the connection to all local IP addresses [IN].
89 * @param local_port If the port is not specified, the allocation of a port
90 * is done automatically by the system [IN].
91 * @return RNET_IN_USE Another connection bound to the same address/port.
92 * RNET_NOT_INITIALIZED NET subsystem not initialized (internal error).
93 * RNET_INTERNAL_ERR Network subsystem failed.
94 * RNET_INVALID_PARAMETER Invalid connection ID.
95 * or Specified address not a valid address
96 * RNET_NOT_READY Still processing a callback function.
97 * RNET_MEMORY_ERR Not enough buffers available, too many connections.
98 * RNET_OK Connection successfully bound.
99 */
100 T_RNET_RET rnet_rt_bind (T_RNET_DESC * desc,
101 T_RNET_IP_ADDR local_addr,
102 T_RNET_PORT local_port);
103
104 /**
105 * Commands a connection to start listening for incoming connections.
106 * When an incoming connection is accepted, an RNET_ACCEPTED message is sent.
107 * The connection ID will have to be bound to a local port
108 * with the rnet_bind() function.
109 *
110 * Note that there is no accept function: After a call to listen,
111 * the application can receive RNET_ACCEPTED messages.
112 *
113 * @param desc Connection identifier [IN].
114 * @return RNET_MEMORY_ERR No available memory for the listening connection.
115 * RNET_NOT_INITIALIZED NET subsystem not initialized (internal error).
116 * RNET_INTERNAL_ERR Network subsystem failed.
117 * or No more socket descriptors available.
118 * RNET_INVALID_PARAMETER Invalid connection ID.
119 * or Connection not bound with bind.
120 * or The ID does not support listening operation.
121 * RNET_IN_USE Connection already connected.
122 * RNET_NOT_READY Still processing a callback function.
123 * RNET_OK Listening successfully started.
124 */
125 T_RNET_RET rnet_rt_listen (T_RNET_DESC *desc);
126
127 /**
128 * Sets up the connection ID to connect to the remote host and sends the
129 * initial SYN segment which opens the connection.
130 *
131 * For the connection-oriented client (TCP), it prepares a connection from the local
132 * to the peer system. The connection oriented client does not need
133 * to call rnet_bind() before rnet_connect(), since rnet_connect() would automatically
134 * use the local address of the client and allocate dynamically a free local port.
135 *
136 * rnet_connect() returns immediately, does not wait for the connection to be properly setup.
137 * The RNET_CONNECT_CFM message is sent when the connection is established.
138 * If the connection could not be properly established, a RNET_ERROR_IND
139 * message is sent.
140 *
141 * A connectionless client (UDP) would use rnet_connect() to locally specify
142 * the remote server, but no connection is open. But the remote address
143 * is then known and does not need to be specified again.
144 * rnet_connect() takes as parameter a fully initialized address structure,
145 * specifying server address and port.
146 *
147 * @param desc Connection identifier [IN].
148 * @param peer_addr Peer address [IN].
149 * @param peer_port Peer port [IN].
150 * @return RNET_MEMORY_ERR No buffer space available.
151 * RNET_NOT_INITIALIZED NET subsystem not initialized (internal error).
152 * RNET_INTERNAL_ERR Network subsystem failed.
153 * or Attempt to connect forcefully rejected.
154 * or Attempt to connect datagram socket to broadcast address
155 * RNET_INVALID_PARAMETER Invalid connection ID.
156 * or Remote address not a valid address (such as ADDR_ANY).
157 * RNET_NOT_SUPPORTED Addresses in the specified family cannot be used with this socket.
158 * RNET_IN_USE Already connected (connection-oriented only).
159 * RNET_NET_UNREACHABLE The network cannot be reached from this host at this time.
160 * RNET_TIMEOUT Attempt to connect timed out without establishing a connection.
161 * RNET_NOT_READY Still processing a callback function.
162 * RNET_OK Connection in progress
163 * RNET_CONNECT_CFM will be sent when the connection
164 * has been successfully completed.
165 */
166 T_RNET_RET rnet_rt_connect (T_RNET_DESC * desc,
167 T_RNET_IP_ADDR peer_addr,
168 T_RNET_PORT peer_port);
169
170 /**
171 * Enqueues the data for sending.
172 *
173 * Data is sent by enqueueing the data with a call to rnet_send().
174 * The function is not-blocking.
175 *
176 * Returns RNET_PARTIAL_SENT if not all data could be sent and the function
177 * needs to be called again later to send the rest of the data. In that case,
178 * the out value of len_p is the number of bytes effectively sent.
179 * The remaining data can be sent when the message RNET_SEND_RDY is received.
180 *
181 * The buffer is copied by RNET, so the application can free the data buffer
182 * when the function returns.
183 *
184 * @param desc Connection identifier [IN].
185 * @param buff Pointer on the data to send [IN].
186 * @param len_p Pointer on the length of the data to send [IN].
187 * Pointer on the length of the data effectively sent [OUT].
188 * @return RNET_MEMORY_ERR Not enough memory is available
189 * RNET_NOT_INITIALIZED NET subsystem not initialized (internal error).
190 * RNET_INTERNAL_ERR Network subsystem failed.
191 * or Requested address is a broadcast address.
192 * RNET_INVALID_PARAMETER The connection ID is invalid.
193 * or The ID is not connected.
194 * or Invalid buff parameter.
195 * or Connection not bound with bind.
196 * RNET_CONN_ABORTED Connection broken due to the "keep-alive" activity
197 * detecting a failure while the operation was in progress.
198 * or Virtual circuit terminated due to a time-out or other failure.
199 * RNET_MSG_SIZE Message oriented connection (UDP), and the message
200 * is larger than the maximum supported by the underlying transport.
201 * RNET_NET_UNREACHABLE Remote host cannot be reached from this host at this time.
202 * RNET_CONN_RESET The virtual circuit was reset by the remote side executing a "hard"
203 * or "abortive" close.
204 * RNET_TIMEOUT The connection has been dropped, because of a
205 * network failure or because the system on the other end went down
206 * without notice.
207 * RNET_NOT_READY Still processing a callback function.
208 * RNET_OK Sending in progress
209 */
210 T_RNET_RET rnet_rt_send (T_RNET_DESC * desc,
211 T_RVF_BUFFER * buff,
212 UINT16 * len_p);
213
214 /**
215 * Read the waiting data (not-blocking).
216 *
217 * Data reception is message based: When the application receives a
218 * T_RNET_RECV_IND message, it can read the data with this
219 * rnet_recv() function.
220 *
221 * The data are copied in the buffer given by the application to RNET
222 * via this rnet_recv function.
223 *
224 * Datagram oriented (UDP)
225 * -----------------------
226 * When an UDP datagram arrives, the receiver application receives
227 * a T_RNET_RECV_IND message. The application can then read the
228 * datagram with the rnet_recv function. The buffer passed to the
229 * function should be big enough to contain a UDP datagram, otherwise
230 * the message is not put in the buffer and the error code
231 * RNET_MSG_SIZE is returned.
232 *
233 * The OUT value of the len_p parameter can have two possible values:
234 * - If there was data to read and no error detected (function
235 * returned RNET_OK), len_p contains the size of the received datagram.
236 * - If there was no error, but no data to read, len_p contains 0.
237 *
238 * RNET will only send a new T_RNET_RECV_IND with a specific descriptor
239 * when a rnet_recv function has been called that returned a len_p parameter
240 * with a 0 value. Therefore, the application should loop on rnet_recv when
241 * it receives a T_RNET_RECV_IND message, like:
242 * UINT16 *len_p = -1;
243 * while (*len_p != 0) {
244 * ret = rnet_recv(desc, buff, len_p);
245 * ...
246 * }
247 *
248 * Stream oriented (TCP)
249 * ---------------------
250 * When a new stream of data arrives on a connection, the receiver
251 * application receives a T_RNET_RECV_IND. It can then read the flow
252 * with the rnet_recv function, until the len_p parameter is returned
253 * with a 0 value.
254 *
255 * The stack will only send a new T_RNET_RECV_IND message when
256 * rnet_recv has been called and has returned the len_p parameter with a 0.
257 *
258 *
259 * @param desc Connection identifier [IN].
260 * @param buff Buffer to store the received data [OUT].
261 * @param len_p Pointer on the length of the passed buffer [IN]
262 * Pointer on the size of the received data in the buffer [OUT].
263 * @return RNET_MEMORY_ERR Not enough memory is available
264 * RNET_NOT_INITIALIZED NET subsystem not initialized (internal error).
265 * RNET_INTERNAL_ERR Network subsystem failed.
266 * RNET_NOT_READY Still processing a callback function.
267 * RNET_INVALID_PARAMETER The connection ID is invalid.
268 * or The ID is not connected.
269 * or Invalid buff parameter.
270 * or Connection not bound with bind.
271 * RNET_CONN_ABORTED Connection broken due to the "keep-alive" activity
272 * detecting a failure while the operation was in progress.
273 * or Virtual circuit terminated due to a time-out or other failure.
274 * RNET_MSG_SIZE The socket is message oriented (UDP), and the message
275 * was too large to fit into the specified buffer and was truncated.
276 * RNET_CONN_RESET The virtual circuit was reset by the remote side executing a "hard"
277 * or "abortive" close.
278 * RNET_TIMEOUT The connection has been dropped, because of a
279 * network failure or because the system on the other end went down
280 * without notice.
281 * RNET_NET_UNREACHABLE Remote host cannot be reached from this host at this time.
282 * RNET_OK Data successfully read.
283 */
284 T_RNET_RET rnet_rt_recv (T_RNET_DESC * desc,
285 T_RVF_BUFFER *buff,
286 UINT16 * len_p);
287
288 T_RNET_RET rnet_rt_recv_from (T_RNET_DESC * desc,
289 T_RVF_BUFFER * buff,
290 UINT16 * len_p,
291 T_RNET_IP_ADDR * from_addr,
292 T_RNET_PORT * from_port);
293
294 /**
295 * Disables the sending on a socket and informs the peer
296 * about it.
297 *
298 * Subsequent calls to the send function are disallowed.
299 * For TCP sockets, a FIN will be sent after all data is sent and acknowledged by the receiver.
300 * The rnet_shutdown function does not frees the connection ID. Any resources attached
301 * to the ID will not be freed until rnet_close is invoked.
302 *
303 * To assure that all data is sent and received on a connection (TCP) before it
304 * is closed, an application should use rnet_shutdown to close connection before calling
305 * rnet_close. For example, to initiate a graceful disconnect:
306 * 1) Call rnet_shutdown.
307 * 2) When RNET_ERROR_IND with RNET_CONN_CLOSED is received, call rnet_recv until
308 * the len parameter is zero.
309 * 3) Call rnet_close.
310 *
311 * Following technique describes how to minimize the chance of problems
312 * occurring during connection teardown. In this example, the client is responsible for
313 * initiating a graceful shutdown.
314 *
315 * Client Side Server Side
316 * (1) Invoke rnet_shutdown to
317 * signal end of session and that
318 * client has no more data to send.
319 * (2) Receive RNET_ERROR_IND with RNET_CONN_CLOSED,
320 * indicating graceful shutdown in progress
321 * and that all data has been received.
322 * (3) Send any remaining response data with rnet_send.
323 * (5') Get RNET_RECV_IND and (4) Invoke rnet_shutdown to
324 * invoke rnet_recv to get any indicate server has no more data to send.
325 * response data sent by server.
326 * (5) Receive RNET_ERROR_IND (4') Invoke rnet_close.
327 * with RNET_CONN_CLOSED.
328 * (6) Invoke rnet_close.
329 *
330 * The timing sequence is maintained from step (1) to step (6) between the client and
331 * the server, except for step (4') and (5') which only has local timing significance in
332 * the sense that step (5) follows step (5') on the client side while step (4') follows
333 * step (4) on the server side, with no timing relationship with the remote party.
334 *
335 * @param desc Connection identifier.
336 * @return RNET_NOT_INITIALIZED NET subsystem not initialized (internal error).
337 * RNET_INTERNAL_ERR Network subsystem failed.
338 * RNET_INVALID_PARAMETER The connection ID is invalid.
339 * The descriptor is not connected (TCP only).
340 * RNET_NOT_READY Still processing a callback function.
341 * RNET_OK Connection shutdown, sending impossible
342 * RNET_ERROR_IND with the parameter RNET_CONN_CLOSED
343 * will be sent to the peer.
344 */
345 T_RNET_RET rnet_rt_shutdown (T_RNET_DESC * desc);
346
347 /**
348 * Closes the connection.
349 *
350 * Use it to release the connection ID so further references to it will fail with
351 * the error RNET_INVALID_PARAMETER.
352 *
353 * An application should always have a matching call to rnet_close for each successful
354 * call to rnet_new to return any resources to the system.
355 *
356 * The function may return RNET_MEMORY_ERR if no memory
357 * was available for closing the connection. If so, the application
358 * should wait and try again either by using the error message
359 * or the polling functionality.
360 * If the close succeeds, the function returns RNET_OK.
361 *
362 * The connection ID is deallocated after a call to rnet_close().
363 *
364 * @param desc Connection identifier.
365 * @return RNET_MEMORY_ERR Not enough memory is available
366 * RNET_NOT_INITIALIZED NET subsystem not initialized (internal error).
367 * RNET_INTERNAL_ERR Network subsystem failed.
368 * RNET_INVALID_PARAMETER The connection ID is invalid.
369 * RNET_NOT_READY Still processing a callback function.
370 * RNET_OK Socket closed.
371 */
372 T_RNET_RET rnet_rt_close (T_RNET_DESC * desc);
373
374 /**
375 * Gets the local address and port of a connection ID.
376 *
377 * @param desc Connection identifier [IN].
378 * @param local_addr_p Local IP address [OUT].
379 * @param local_port_p Local port [OUT].
380 * @return RNET_NOT_INITIALIZED NET subsystem not initialized (internal error).
381 * RNET_INTERNAL_ERR Network subsystem failed.
382 * RNET_INVALID_PARAMETER The connection ID is invalid.
383 * or Not bound to an address with bind.
384 * or ADDR_ANY is specified in bind but connection not yet occurred.
385 * RNET_NOT_READY Still processing a callback function.
386 * RNET_OK Local address/port successfully get.
387 */
388 T_RNET_RET rnet_rt_get_local_addr_port (T_RNET_DESC * desc,
389 T_RNET_IP_ADDR * local_addr_p,
390 T_RNET_PORT * local_port_p);
391
392 /**
393 * Use to determine the amount of data pending in the network's input buffer
394 * that can be read from the connection ID.
395 *
396 * If desc is stream oriented (TCP), returns the amount of data that can be read
397 * in a single call to the rnet_recv function; this might not be the same as the
398 * total amount of data queued on the socket.
399 * If desc is message oriented (UDP), returns the size of the first datagram
400 * (message) queued on the socket.
401 *
402 * @param desc Connection identifier [IN].
403 * @param size_p Pointer to an unsigned int in which the result is stored [OUT].
404 * @return RNET_NOT_INITIALIZED NET subsystem not initialized (internal error).
405 * RNET_INTERNAL_ERR Network subsystem failed.
406 * RNET_INVALID_PARAMETER The connection ID is invalid.
407 * RNET_NOT_READY Still processing a callback function.
408 * RNET_OK Value successfully get.
409 */
410 T_RNET_RET rnet_rt_get_buff_size (T_RNET_DESC * desc,
411 UINT32 * size_p);
412
413 /**
414 * Requests host information corresponding to a host name or to a
415 * network address.
416 *
417 * One of the two parameters name or addr must be NULL.
418 *
419 * This function is bridge function sending a corresponding message to RNET.
420 * The message RNET_HOST_INFO is sent back when the requested information
421 * is available.
422 *
423 * Note that this function does not need a connection identifier and specifies
424 * its own return path.
425 *
426 * @param name Name of the host to resolve [IN].
427 * @param addr Network address [IN].
428 * @param return_path Return path for sending the response.
429 * @param user_data Pointer on some user-defined data that
430 * will be contained in the RNET_HOST_INFO message [IN].
431 * @return RNET_MEMORY_ERR Not enough memory is available.
432 * RNET_OK The message could be correctly send.
433 */
434 T_RNET_RET rnet_rt_get_host_info (char *name,
435 T_RNET_IP_ADDR addr,
436 T_RV_RETURN_PATH return_path,
437 void * user_data);
438
439 /*
440 * Following functions are not directly part of the networking API,
441 * but they are used to retrieve some simple information from a connection
442 * descriptor. They are simple blocking functions, not sending any messages.
443 */
444
445 /**
446 * Retrieves the protocol associated to a connection descriptor.
447 *
448 * @param desc Connection identifier.
449 * @return A value of the T_RNET_IPPROTO enumeration.
450 */
451 T_RNET_IPPROTO rnet_rt_get_proto (T_RNET_DESC *desc);
452
453 /**
454 * Associates an application specific pointer to a connection ID.
455 *
456 * @param desc Connection identifier.
457 * @param user_data Pointer that can be used by an application to store
458 * application specific data.
459 */
460 void rnet_rt_set_user_data (T_RNET_DESC *desc, void *user_data);
461
462 /**
463 * Returns the application specific pointer associated to the connection ID.
464 *
465 * @param desc Connection identifier.
466 * @return Application specific data.
467 */
468 void * rnet_rt_get_user_data (T_RNET_DESC *desc);
469 /*@}*/
470
471 /**
472 * Gets the maximum send size of a message.
473 *
474 * @param desc Connection identifier [IN].
475 * @param size_p Maximum send size [OUT].
476 * @return RNET_NOT_INITIALIZED NET subsystem not initialized (internal error).
477 * RNET_INTERNAL_ERR Network subsystem failed.
478 * RNET_INVALID_PARAMETER The connection ID is invalid.
479 * RNET_NOT_READY Still processing a callback function.
480 * RNET_OK Local address/port successfully get.
481 */
482
483 T_RNET_RET rnet_rt_get_max_packet_size (T_RNET_DESC *desc,
484 UINT32 *size_p);
485
486 /**
487 * NexGenIP specific API
488 */
489
490 T_RNET_RET rnet_rt_route_add( T_RNET_IP_ADDR dest, T_RNET_IP_ADDR netmask, T_RNET_IP_ADDR gateway);
491 T_RNET_RET rnet_rt_route_del( T_RNET_IP_ADDR dest);
492 T_RNET_RET rnet_rt_route_default( T_RNET_IP_ADDR gateway);
493
494 T_RNET_RET rnet_rt_if_setaddr( const char *ifname, T_RNET_IP_ADDR addr, T_RNET_IP_ADDR netmask);
495 T_RNET_RET rnet_rt_if_getaddr( const char *ifname, T_RNET_IP_ADDR *addr, T_RNET_IP_ADDR *netmask);
496 T_RNET_RET rnet_rt_if_setdstaddr( const char *ifname, T_RNET_IP_ADDR dstaddr);
497 T_RNET_RET rnet_rt_if_getdstaddr( const char *ifname, T_RNET_IP_ADDR *dstaddr);
498
499 T_RNET_RET rnet_rt_set_resolver( const char *domain, T_RNET_IP_ADDR dns1, T_RNET_IP_ADDR dns2);
500
501 #ifdef __cplusplus
502 }
503 #endif
504
505 #endif /*__RNET_RT_API_H_*/
506
507 #endif /* ifdef RNET_CFG_REAL_TRANSPORT */
508