FreeCalypso > hg > fc-magnetite

comparison src/g23m-fad/tcpip/rnet/rnet_api.h @ 174:90eb61ecd093

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
src/g23m-fad: initial import from TCS3.2/LoCosto
author Mychaela Falconia <falcon@freecalypso.org>
date Wed, 12 Oct 2016 05:40:46 +0000
parents
children
comparison
equal deleted inserted replaced
173:bf64d785238a 174:90eb61ecd093
1 /**
2 * @file rnet_api.h
3 *
4 * Riviera NET.
5 *
6 * Declarations of the Riviera TCP/IP stack asynchronous
7 * (non-blocking) API.
8 * See the Readme.txt file.
9 *
10 * @author Vincent Oberle (v-oberle@ti.com)
11 * @version 0.1
12 */
13
14 /*
15 * History:
16 *
17 * Date Author Modification
18 * --------------------------------------------------
19 * 01/25/2002 Vincent Oberle Create
20 * 03/14/2002 Vincent Oberle Added rnet_shutdown
21 *
22 * (C) Copyright 2002 by Texas Instruments Incorporated, All Rights Reserved
23 */
24
25 #ifndef __RNET_API_H_
26 #define __RNET_API_H_
27
28 /*
29 * IMPORTANT NOTE FOR WINDOWS 2000 USERS
30 *
31 * It has been observed that the Winsocket version of the RNET implementation
32 * does not function correctly under Windows 2000. Connection to a host on the
33 * Internet does not work.
34 * This problem does not appear under NT4 and XP.
35 */
36
37 #include "rv_general.h"
38 #include "rvf_api.h"
39
40 #include "rnet_cfg.h"
41 #include "rnet_ip_addr.h"
42
43 #ifdef __cplusplus
44 extern "C"
45 {
46 #endif
47
48 /***********************
49 * Types and constants *
50 ***********************/
51
52 /**
53 * Protocols supported.
54 *
55 * Even if the interface has some similarities to the socket API,
56 * only the Internet protocols TCP and UDP are supported.
57 *
58 * RNET_IPPROTO_UNDEFINED can never be passed to a function,
59 * but only returned by rnet_get_proto when the stack gets corrupted
60 * or any other problem.
61 */
62 typedef enum {
63 RNET_IPPROTO_UNDEFINED = 0,
64 RNET_IPPROTO_TCP = 6,
65 RNET_IPPROTO_UDP = 17
66 /* RNET_IPPROTO_ICMP = 1 not supported (yet?) */
67 } T_RNET_IPPROTO;
68
69 /**
70 * Traffic class.
71 *
72 * @todo Values to be defined.
73 */
74 typedef enum {
75 RNET_TRAFFIC_CLASS_DEFAULT,
76 RNET_TRAFFIC_CLASS_WAP,
77 RNET_TRAFFIC_CLASS_FTP,
78 /* or */
79 RNET_TRAFFIC_CLASS_LOWDELAY,
80 RNET_TRAFFIC_CLASS_BACKGROUND,
81 RNET_TRAFFIC_CLASS_BEST_EFFORT,
82 RNET_TRAFFIC_CLASS_NETWORK
83 } T_RNET_TRAFFIC_CLASS;
84
85 /**
86 * Connection identifier.
87 *
88 * This structure is equivalent to the socket descriptor.
89 * The content of this structure is specific to the TCP/IP implementation
90 * and not seen by the user of RNET.
91 * In no case should the application developer manipulate directly the content
92 * of the structure. He/she only sees a pointer on it.
93 */
94 #ifdef _WINDOWS
95 #if defined RNET_CFG_WINSOCK
96 typedef struct T_RNET_WS_DESC T_RNET_DESC;
97 #elif defined RNET_CFG_REAL_TRANSPORT
98 typedef struct T_RNET_RT_SOCK T_RNET_DESC;
99 #endif
100 #else
101 #if defined RNET_CFG_BRIDGE
102 typedef struct T_RNET_BR_DESC T_RNET_DESC;
103 #elif defined RNET_CFG_REAL_TRANSPORT
104 typedef struct T_RNET_RT_SOCK T_RNET_DESC;
105 #endif
106 #endif
107
108 /**
109 * Net package return values and error codes. They are both used for
110 * API function return values and in the RNET_ERROR_IND error message.
111 *
112 * Please note that some are specific to RNET and are not found
113 * among the standard Riviera return code.
114 */
115 typedef enum {
116 /*
117 * Standard RV return values
118 ****************************/
119
120 RNET_OK = RV_OK,
121
122 RNET_MEMORY_ERR = RV_MEMORY_ERR,
123
124 RNET_INVALID_PARAMETER = RV_INVALID_PARAMETER,
125
126 /**
127 * The protocol type or the specified protocol is not
128 * supported by the system.
129 * The specified feature is not implemented.
130 */
131 RNET_NOT_SUPPORTED = RV_NOT_SUPPORTED,
132
133 RNET_NOT_READY = RV_NOT_READY,
134
135 RNET_INTERNAL_ERR = RV_INTERNAL_ERR,
136
137 /*
138 * RNET specific return values
139 ******************************/
140
141 /**
142 * Another connection is bound to the same port,
143 * address or socket.
144 */
145 RNET_IN_USE = -50,
146
147 /**
148 * The protocol stack wasn't initialised.
149 * See rnet_ws_startup().
150 */
151 RNET_NOT_INITIALIZED = -51,
152
153 /**
154 * The network cannot be reached from this host at this time.
155 */
156 RNET_NET_UNREACHABLE = -52,
157
158 /**
159 * Attempt to connect timed out without establishing a connection.
160 */
161 RNET_TIMEOUT = -53,
162
163 /**
164 * The attempt to connect was forcefully rejected.
165 */
166 RNET_CONN_REFUSED = -54,
167
168 /**
169 * The connection was reset by the remote side.
170 */
171 RNET_CONN_RESET = -55,
172
173 /**
174 * The connection was terminated due to a time-out or other failure.
175 */
176 RNET_CONN_ABORTED = -56,
177
178 /**
179 * The connection was gracefully closed.
180 */
181 RNET_CONN_CLOSED = -57,
182
183 /**
184 * The connection is message oriented (UDP), and the message is larger than the
185 * maximum supported by the underlying transport.
186 */
187 RNET_MSG_SIZE = -58,
188
189 /**
190 * Not all bytes have been sent in a send operations.
191 */
192 RNET_PARTIAL_SENT = -59,
193
194 /**
195 * For host search.
196 * Indicates that a host was not found.
197 */
198 RNET_HOST_NOT_FOUND = -60
199
200 } T_RNET_RET;
201
202 /*************
203 * Functions *
204 *************/
205
206 /**
207 * Creates a new connection identifier (T_RNET_DESC).
208 *
209 * The connection ID is not active until it has either been bound
210 * to a local address or connected to a remote address.
211 *
212 * @param proto Protocol that should be used [IN].
213 * @param desc Connection identifier created [OUT].
214 * @param return_path Return path that should be used to send
215 * the messages like accept, connect, etc [IN].
216 * @return RNET_MEMORY_ERR No available memory to create the new connection id.
217 * RNET_NOT_INITIALIZED NET subsystem not initialized (internal error).
218 * RNET_INTERNAL_ERR Network subsystem failed.
219 * or No more socket descriptors available.
220 * RNET_NOT_READY Still processing a callback function.
221 * RNET_NOT_SUPPORTED Specified protocol not supported.
222 * RNET_OK Connection ID successfully created.
223 */
224 T_RNET_RET rnet_new (T_RNET_IPPROTO proto,
225 T_RNET_DESC ** desc,
226 T_RV_RETURN_PATH return_path);
227
228 /**
229 * Sets the traffic class of a connection ID.
230 *
231 * Note that this function is NOT implemented under Windows.
232 *
233 * @param desc Connection identifier [IN].
234 * @param traffic_class Traffic class, see T_RNET_TRAFFIC_CLASS
235 * for more details.
236 * @return RNET_NOT_INITIALIZED NET subsystem not initialized (internal error).
237 * RNET_INTERNAL_ERR Network subsystem failed.
238 * RNET_INVALID_PARAMETER Invalid connection ID.
239 * or Specified traffic class not valid.
240 * RNET_OK Traffic class successfully set.
241 */
242 T_RNET_RET rnet_set_traffic_class (T_RNET_DESC * desc,
243 T_RNET_TRAFFIC_CLASS traffic_class);
244
245 /**
246 * Binds the connection to a local IP address and port number.
247 *
248 * @param desc Connection identifier [IN].
249 * @param local_addr Local IP address
250 * The IP address can be specified as RNET_IP_ADDR_ANY
251 * in order to bind the connection to all local IP addresses [IN].
252 * @param local_port If the port is not specified, the allocation of a port
253 * is done automatically by the system [IN].
254 * @return RNET_IN_USE Another connection bound to the same address/port.
255 * RNET_NOT_INITIALIZED NET subsystem not initialized (internal error).
256 * RNET_INTERNAL_ERR Network subsystem failed.
257 * RNET_INVALID_PARAMETER Invalid connection ID.
258 * or Specified address not a valid address
259 * RNET_NOT_READY Still processing a callback function.
260 * RNET_MEMORY_ERR Not enough buffers available, too many connections.
261 * RNET_OK Connection successfully bound.
262 */
263 T_RNET_RET rnet_bind (T_RNET_DESC * desc,
264 T_RNET_IP_ADDR local_addr,
265 T_RNET_PORT local_port);
266
267 /**
268 * Commands a connection to start listening for incoming connections.
269 * When an incoming connection is accepted, an RNET_CONNECT_IND message is sent.
270 * The connection ID will have to be bound to a local port
271 * with the rnet_bind() function.
272 *
273 * Note that there is no accept function: After a call to listen,
274 * the application can receive RNET_ACCEPTED messages.
275 *
276 * @param desc Connection identifier [IN].
277 * @return RNET_MEMORY_ERR No available memory for the listening connection.
278 * RNET_NOT_INITIALIZED NET subsystem not initialized (internal error).
279 * RNET_INTERNAL_ERR Network subsystem failed.
280 * or No more socket descriptors available.
281 * RNET_INVALID_PARAMETER Invalid connection ID.
282 * or Connection not bound with bind.
283 * or The ID does not support listening operation.
284 * RNET_IN_USE Connection already connected.
285 * RNET_NOT_READY Still processing a callback function.
286 * RNET_OK Listening successfully started.
287 */
288 T_RNET_RET rnet_listen (T_RNET_DESC *desc);
289
290 /**
291 * Sets up the connection ID to connect to the remote host and sends the
292 * initial SYN segment which opens the connection.
293 *
294 * For the connection-oriented client (TCP), it prepares a connection from the local
295 * to the peer system. The connection oriented client does not need
296 * to call rnet_bind() before rnet_connect(), since rnet_connect() would automatically
297 * use the local address of the client and allocate dynamically a free local port.
298 *
299 * rnet_connect() returns immediately, does not wait for the connection to be properly setup.
300 * The RNET_CONNECT_CFM message is sent when the connection is established.
301 * If the connection could not be properly established, a RNET_ERROR_IND
302 * message is sent.
303 *
304 * A connectionless client (UDP) would use rnet_connect() to locally specify
305 * the remote server, but no connection is open. But the remote address
306 * is then known and does not need to be specified again.
307 * rnet_connect() takes as parameter a fully initialized address structure,
308 * specifying server address and port.
309 *
310 * @param desc Connection identifier [IN].
311 * @param peer_addr Peer address [IN].
312 * @param peer_port Peer port [IN].
313 * @return RNET_MEMORY_ERR No buffer space available.
314 * RNET_NOT_INITIALIZED NET subsystem not initialized (internal error).
315 * RNET_INTERNAL_ERR Network subsystem failed.
316 * or Attempt to connect forcefully rejected.
317 * or Attempt to connect datagram socket to broadcast address
318 * RNET_INVALID_PARAMETER Invalid connection ID.
319 * or Remote address not a valid address (such as ADDR_ANY).
320 * RNET_NOT_SUPPORTED Addresses in the specified family cannot be used with this socket.
321 * RNET_IN_USE Already connected (connection-oriented only).
322 * RNET_NET_UNREACHABLE The network cannot be reached from this host at this time.
323 * RNET_TIMEOUT Attempt to connect timed out without establishing a connection.
324 * RNET_NOT_READY Still processing a callback function.
325 * RNET_OK Connection in progress
326 * RNET_CONNECT_CFM will be sent when the connection
327 * has been successfully completed.
328 */
329 T_RNET_RET rnet_connect (T_RNET_DESC * desc,
330 T_RNET_IP_ADDR peer_addr,
331 T_RNET_PORT peer_port);
332
333 /**
334 * Enqueues the data for sending.
335 *
336 * Data is sent by enqueueing the data with a call to rnet_send().
337 * The function is not-blocking.
338 *
339 * Returns RNET_PARTIAL_SENT if not all data could be sent and the function
340 * needs to be called again later to send the rest of the data. In that case,
341 * the out value of len_p is the number of bytes effectively sent.
342 * The remaining data can be sent when the message RNET_SEND_RDY is received.
343 *
344 * If no RNET_PARTIAL_SENT is returned, but RNET_OK, more data can be
345 * immediately sent. No RNET_SEND_RDY is sent to the SWE.
346 *
347 * The buffer is copied by RNET, so the application can free the data buffer
348 * when the function returns.
349 *
350 * @param desc Connection identifier [IN].
351 * @param buff Pointer on the data to send [IN].
352 * @param len_p Pointer on the length of the data to send [IN].
353 * Pointer on the length of the data effectively sent [OUT].
354 * @return RNET_MEMORY_ERR Not enough memory is available
355 * RNET_NOT_INITIALIZED NET subsystem not initialized (internal error).
356 * RNET_INTERNAL_ERR Network subsystem failed.
357 * or Requested address is a broadcast address.
358 * RNET_INVALID_PARAMETER The connection ID is invalid.
359 * or The ID is not connected.
360 * or Invalid buff parameter.
361 * or Connection not bound with bind.
362 * RNET_CONN_ABORTED Connection broken due to the "keep-alive" activity
363 * detecting a failure while the operation was in progress.
364 * or Virtual circuit terminated due to a time-out or other failure.
365 * RNET_MSG_SIZE Message oriented connection (UDP), and the message
366 * is larger than the maximum supported by the underlying transport.
367 * RNET_NET_UNREACHABLE Remote host cannot be reached from this host at this time.
368 * RNET_CONN_RESET The virtual circuit was reset by the remote side executing a "hard"
369 * or "abortive" close.
370 * RNET_TIMEOUT The connection has been dropped, because of a
371 * network failure or because the system on the other end went down
372 * without notice.
373 * RNET_NOT_READY Still processing a callback function.
374 * RNET_OK Sending in progress.
375 */
376 T_RNET_RET rnet_send (T_RNET_DESC * desc,
377 T_RVF_BUFFER * buff,
378 UINT16 * len_p);
379
380 /**
381 * Read the waiting data (not-blocking).
382 *
383 * Data reception is message based: When the application receives a
384 * T_RNET_RECV_IND message, it can read the data with this
385 * rnet_recv() function.
386 *
387 * The data are copied in the buffer given by the application to RNET
388 * via this rnet_recv function.
389 *
390 * Datagram oriented (UDP)
391 * -----------------------
392 * When an UDP datagram arrives, the receiver application receives
393 * a T_RNET_RECV_IND message. The application can then read the
394 * datagram with the rnet_recv function. The buffer passed to the
395 * function should be big enough to contain a UDP datagram, otherwise
396 * the message is not put in the buffer and the error code
397 * RNET_MSG_SIZE is returned.
398 *
399 * The OUT value of the len_p parameter can have two possible values:
400 * - If there was data to read and no error detected (function
401 * returned RNET_OK), len_p contains the size of the received datagram.
402 * - If there was no error, but no data to read, len_p contains 0.
403 *
404 * RNET will only send a new T_RNET_RECV_IND with a specific descriptor
405 * when a rnet_recv function has been called that returned a len_p parameter
406 * with a 0 value. Therefore, the application should loop on rnet_recv when
407 * it receives a T_RNET_RECV_IND message, like:
408 * UINT16 *len_p = -1;
409 * while (*len_p != 0) {
410 * ret = rnet_recv(desc, buff, len_p);
411 * ...
412 * }
413 *
414 * Stream oriented (TCP)
415 * ---------------------
416 * When a new stream of data arrives on a connection, the receiver
417 * application receives a T_RNET_RECV_IND. It can then read the flow
418 * with the rnet_recv function, until the len_p parameter is returned
419 * with a 0 value.
420 *
421 * The stack will only send a new T_RNET_RECV_IND message when
422 * rnet_recv has been called and has returned the len_p parameter with a 0.
423 *
424 *
425 * @param desc Connection identifier [IN].
426 * @param buff Buffer to store the received data [OUT].
427 * @param len_p Pointer on the length of the passed buffer [IN]
428 * Pointer on the size of the received data in the buffer [OUT].
429 * @return RNET_MEMORY_ERR Not enough memory is available
430 * RNET_NOT_INITIALIZED NET subsystem not initialized (internal error).
431 * RNET_INTERNAL_ERR Network subsystem failed.
432 * RNET_NOT_READY Still processing a callback function.
433 * RNET_INVALID_PARAMETER The connection ID is invalid.
434 * or The ID is not connected.
435 * or Invalid buff parameter.
436 * or Connection not bound with bind.
437 * RNET_CONN_ABORTED Connection broken due to the "keep-alive" activity
438 * detecting a failure while the operation was in progress.
439 * or Virtual circuit terminated due to a time-out or other failure.
440 * RNET_MSG_SIZE The socket is message oriented (UDP), and the message
441 * was too large to fit into the specified buffer and was truncated.
442 * RNET_CONN_RESET The virtual circuit was reset by the remote side executing a "hard"
443 * or "abortive" close.
444 * RNET_TIMEOUT The connection has been dropped, because of a
445 * network failure or because the system on the other end went down
446 * without notice.
447 * RNET_NET_UNREACHABLE Remote host cannot be reached from this host at this time.
448 * RNET_OK Data successfully read.
449 */
450 T_RNET_RET rnet_recv (T_RNET_DESC * desc,
451 T_RVF_BUFFER *buff,
452 UINT16 * len_p);
453
454 /**
455 * Read the waiting data (not-blocking). Similar to rnet_recv,
456 * BUT FOR UDP ONLY.
457 *
458 * See rnet_recv.
459 *
460 *
461 * @param desc Connection identifier [IN].
462 * @param buff Buffer to store the received data [OUT].
463 * @param len_p Pointer on the length of the passed buffer [IN]
464 * Pointer on the size of the received data in the buffer [OUT].
465 * @return RNET_MEMORY_ERR Not enough memory is available
466 * RNET_NOT_INITIALIZED NET subsystem not initialized (internal error).
467 * RNET_INTERNAL_ERR Network subsystem failed.
468 * RNET_NOT_READY Still processing a callback function.
469 * RNET_INVALID_PARAMETER The connection ID is invalid.
470 * or The ID is connected.
471 * or Invalid buff parameter.
472 * or Connection not bound with bind.
473 * RNET_CONN_ABORTED Connection broken due to the "keep-alive" activity
474 * detecting a failure while the operation was in progress.
475 * or Virtual circuit terminated due to a time-out or other failure.
476 * RNET_MSG_SIZE The socket is message oriented (UDP), and the message
477 * was too large to fit into the specified buffer and was truncated.
478 * RNET_CONN_RESET The virtual circuit was reset by the remote side executing a "hard"
479 * or "abortive" close.
480 * RNET_TIMEOUT The connection has been dropped, because of a
481 * network failure or because the system on the other end went down
482 * without notice.
483 * RNET_NET_UNREACHABLE Remote host cannot be reached from this host at this time.
484 * RNET_OK Data successfully read.
485 */
486 T_RNET_RET rnet_recv_from (T_RNET_DESC * desc,
487 T_RVF_BUFFER * buff,
488 UINT16 * len_p,
489 T_RNET_IP_ADDR * from_addr,
490 T_RNET_PORT * from_port);
491
492 /**
493 * Disables the sending on a socket and informs the peer
494 * about it.
495 *
496 * Subsequent calls to the send function are disallowed.
497 * For TCP sockets, a FIN will be sent after all data is sent and acknowledged by the receiver.
498 * The rnet_shutdown function does not frees the connection ID. Any resources attached
499 * to the ID will not be freed until rnet_close is invoked.
500 *
501 * To assure that all data is sent and received on a connection (TCP) before it
502 * is closed, an application should use rnet_shutdown to close connection before calling
503 * rnet_close. For example, to initiate a graceful disconnect:
504 * 1) Call rnet_shutdown.
505 * 2) When RNET_ERROR_IND with RNET_CONN_CLOSED is received, call rnet_recv until
506 * the len parameter is zero.
507 * 3) Call rnet_close.
508 *
509 * Following technique describes how to minimize the chance of problems
510 * occurring during connection teardown. In this example, the client is responsible for
511 * initiating a graceful shutdown.
512 *
513 * Client Side Server Side
514 * (1) Invoke rnet_shutdown to
515 * signal end of session and that
516 * client has no more data to send.
517 * (2) Receive RNET_ERROR_IND with RNET_CONN_CLOSED,
518 * indicating graceful shutdown in progress
519 * and that all data has been received.
520 * (3) Send any remaining response data with rnet_send.
521 * (5') Get RNET_RECV_IND and (4) Invoke rnet_shutdown to
522 * invoke rnet_recv to get any indicate server has no more data to send.
523 * response data sent by server.
524 * (5) Receive RNET_ERROR_IND (4') Invoke rnet_close.
525 * with RNET_CONN_CLOSED.
526 * (6) Invoke rnet_close.
527 *
528 * The timing sequence is maintained from step (1) to step (6) between the client and
529 * the server, except for step (4') and (5') which only has local timing significance in
530 * the sense that step (5) follows step (5') on the client side while step (4') follows
531 * step (4) on the server side, with no timing relationship with the remote party.
532 *
533 * @param desc Connection identifier.
534 * @return RNET_NOT_INITIALIZED NET subsystem not initialized (internal error).
535 * RNET_INTERNAL_ERR Network subsystem failed.
536 * RNET_INVALID_PARAMETER The connection ID is invalid.
537 * The descriptor is not connected (TCP only).
538 * RNET_NOT_READY Still processing a callback function.
539 * RNET_OK Connection shutdown, sending impossible
540 * RNET_ERROR_IND with the parameter RNET_CONN_CLOSED
541 * will be sent to the peer.
542 */
543 T_RNET_RET rnet_shutdown (T_RNET_DESC * desc);
544
545 /**
546 * Closes the connection.
547 *
548 * Use it to release the connection ID so further references to it will fail with
549 * the error RNET_INVALID_PARAMETER.
550 *
551 * An application should always have a matching call to rnet_close for each successful
552 * call to rnet_new to return any resources to the system.
553 *
554 * The function may return RNET_MEMORY_ERR if no memory
555 * was available for closing the connection. If so, the application
556 * should wait and try again either by using the error message
557 * or the polling functionality.
558 * If the close succeeds, the function returns RNET_OK.
559 *
560 * The connection ID is deallocated by a call to rnet_close().
561 *
562 * IMPORTANT: If an application wants to call rnet_close after having received
563 * a close event (RNET_ERROR_IND message with error parameter set to RNET_CONN_CLOSED),
564 * it should check that there are no remaining data to be read (data arrived after
565 * the RNET_ERROR_IND message, so that no RNET_RECV_IND was received yet).
566 * A way to do it is:
567 * T_RVF_BUFFER * buff;
568 * UINT16 len;
569 *
570 * RNET_TRACE_LOW("Read remaining data");
571 * len = 100;
572 * while (len > 0) {
573 * rvf_get_buf(rtest_get_mb_id(), len, (T_RVF_BUFFER**)&buff);
574 * rnet_recv(error_ind_msg_p->desc, buff, (UINT16*)&len);
575 * rvf_send_trace(buff, len, NULL_PARAM, RV_TRACE_LEVEL_DEBUG_LOW, RTEST_USE_ID);
576 * rvf_free_buf(buff);
577 * }
578 *
579 * @param desc Connection identifier.
580 * @return RNET_MEMORY_ERR Not enough memory is available
581 * RNET_NOT_INITIALIZED NET subsystem not initialized (internal error).
582 * RNET_INTERNAL_ERR Network subsystem failed.
583 * RNET_INVALID_PARAMETER The connection ID is invalid.
584 * RNET_NOT_READY Still processing a callback function.
585 * RNET_OK Socket closed.
586 */
587 T_RNET_RET rnet_close (T_RNET_DESC * desc);
588
589 /**
590 * Gets the local address and port of a connection ID.
591 *
592 * @param desc Connection identifier [IN].
593 * @param local_addr_p Local IP address [OUT].
594 * @param local_port_p Local port [OUT].
595 * @return RNET_NOT_INITIALIZED NET subsystem not initialized (internal error).
596 * RNET_INTERNAL_ERR Network subsystem failed.
597 * RNET_INVALID_PARAMETER The connection ID is invalid.
598 * or Not bound to an address with bind.
599 * or ADDR_ANY is specified in bind but connection not yet occurred.
600 * RNET_NOT_READY Still processing a callback function.
601 * RNET_OK Local address/port successfully get.
602 */
603 T_RNET_RET rnet_get_local_addr_port (T_RNET_DESC * desc,
604 T_RNET_IP_ADDR * local_addr_p,
605 T_RNET_PORT * local_port_p);
606
607 /**
608 * Use to determine the amount of data pending in the network's input buffer
609 * that can be read from the connection ID.
610 *
611 * If desc is stream oriented (TCP), returns the amount of data that can be read
612 * in a single call to the rnet_recv function; this might not be the same as the
613 * total amount of data queued on the socket.
614 * If desc is message oriented (UDP), returns the size of the first datagram
615 * (message) queued on the socket.
616 *
617 * @param desc Connection identifier [IN].
618 * @param size_p Pointer to an unsigned int in which the result is stored [OUT].
619 * @return RNET_NOT_INITIALIZED NET subsystem not initialized (internal error).
620 * RNET_INTERNAL_ERR Network subsystem failed.
621 * RNET_INVALID_PARAMETER The connection ID is invalid.
622 * RNET_NOT_READY Still processing a callback function.
623 * RNET_OK Value successfully get.
624 */
625 T_RNET_RET rnet_get_buff_size (T_RNET_DESC * desc,
626 UINT32 * size_p);
627
628 /**
629 * Indicates the maximum send size of a message for message-oriented
630 * descriptor (UDP) as implemented by a particular service provider.
631 * It has no meaning for TCP.
632 *
633 * @param desc Connection identifier [IN].
634 * @param size_p Pointer to an unsigned int in which the result is stored [OUT].
635 */
636 T_RNET_RET rnet_get_max_packet_size (T_RNET_DESC * desc,
637 UINT32 * size_p);
638
639 /**
640 * Requests host information corresponding to a host name or to a
641 * network address.
642 *
643 * One of the two parameters name or addr must be NULL.
644 *
645 * This function is bridge function sending a corresponding message to RNET.
646 * The message RNET_HOST_INFO is sent back when the requested information
647 * is available or if the request failed:
648 * If RNET_HOST_INFO "error" parameter is RNET_OK, no error occured and
649 * the host_name, host_addr and user_data parameters are valid.
650 * If RNET_HOST_INFO "error" parameter is different from RNET_OK, the host
651 * information could not be retrieved and only user_data is valid.
652 *
653 * Note that this function does not need a connection identifier and specifies
654 * its own return path.
655 *
656 * @param name Name of the host to resolve [IN].
657 * @param addr Network address [IN].
658 * @param return_path Return path for sending the response [IN].
659 * @param user_data Pointer on some user-defined data that
660 * will be contained in the RNET_HOST_INFO message [IN].
661 * @return RNET_MEMORY_ERR Not enough memory is available.
662 * RNET_OK The message could be correctly send.
663 */
664 T_RNET_RET rnet_get_host_info (char *name,
665 T_RNET_IP_ADDR addr,
666 T_RV_RETURN_PATH return_path,
667 void * user_data);
668
669 /*
670 * Following functions are not directly part of the networking API,
671 * but they are used to retrieve some simple information from a connection
672 * descriptor. They are simple blocking functions, not sending any messages.
673 */
674
675 /**
676 * Retrieves the protocol associated to a connection descriptor.
677 *
678 * @param desc Connection identifier.
679 * @return A value of the T_RNET_IPPROTO enumeration.
680 */
681 T_RNET_IPPROTO rnet_get_proto (T_RNET_DESC *desc);
682
683 /**
684 * Associates an application specific pointer to a connection ID.
685 *
686 * @param desc Connection identifier.
687 * @param user_data Pointer that can be used by an application to store
688 * application specific data.
689 */
690 void rnet_set_user_data (T_RNET_DESC *desc, void *user_data);
691
692 /**
693 * Returns the application specific pointer associated to the connection ID.
694 *
695 * @param desc Connection identifier.
696 * @return Application specific data.
697 */
698 void * rnet_get_user_data (T_RNET_DESC *desc);
699
700 #ifdef __cplusplus
701 }
702 #endif
703
704 #endif /* __RNET_API_H_ */
705