FreeCalypso > hg > fc-selenite
diff src/g23m-fad/tcpip/rnet/rnet_rt/rnet_rt_api.h @ 1:d393cd9bb723
src/g23m-*: initial import from Magnetite
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Sun, 15 Jul 2018 04:40:46 +0000 |
parents | |
children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/g23m-fad/tcpip/rnet/rnet_rt/rnet_rt_api.h Sun Jul 15 04:40:46 2018 +0000 @@ -0,0 +1,508 @@ +/** + * @file rnet_rt_api.h + * + * API Definition for RNET_RT SWE. + * + * @author Jose Yp-Tcha (j-yp-tcha@ti.com) + * @version 0.1 + */ + +/* + * $Id: rnet_rt_api.h,v 1.5 2002/10/30 15:23:34 rf Exp $ + * $Name: ti_20021030 $ + * + * History: + * + * Date Author Modification + * ------------------------------------------------------------------- + * 3/19/2002 Jose Yp-Tcha (j-yp-tcha@ti.com) Create. + * 4/3/2002 Regis Feneon ngip api + * + * (C) Copyright 2002 by TI, All Rights Reserved + */ + +#include "rnet_cfg.h" + +#ifdef RNET_CFG_REAL_TRANSPORT + +#ifndef __RNET_RT_API_H_ +#define __RNET_RT_API_H_ + +#include "rvm_gen.h" /* Generic RVM types and functions. */ +#include "rnet_api.h" + +#ifdef __cplusplus +extern "C" +{ +#endif + +/** + * @name RNET_RT Return type and return values. + * + * Currently they are the standard RV return types, but they may + * be customized in the future. + */ +/*@{*/ + +#define RNET_RT_OK RV_OK +#define RNET_RT_NOT_SUPPORTED RV_NOT_SUPPORTED +#define RNET_RT_MEMORY_ERR RV_MEMORY_ERR +#define RNET_RT_INTERNAL_ERR RV_INTERNAL_ERR +/*@}*/ + +/** + * @name API functions + * + * API functions declarations (bridge functions). + */ +/*@{*/ + +/** + * Creates a new connection identifier (T_RNET_DESC). + * + * The connection ID is not active until it has either been bound + * to a local address or connected to a remote address. + * + * @param proto Protocol that should be used [IN]. + * @param desc Connection identifier created [OUT]. + * @param return_path Return path that should be used to send + * the messages like accept, connect, etc [IN]. + * @return RNET_MEMORY_ERR No available memory to create the new connection id. + * RNET_NOT_INITIALIZED NET subsystem not initialized (internal error). + * RNET_INTERNAL_ERR Network subsystem failed. + * or No more socket descriptors available. + * RNET_NOT_READY Still processing a callback function. + * RNET_NOT_SUPPORTED Specified protocol not supported. + * RNET_OK Connection ID successfully created. + */ +T_RNET_RET rnet_rt_new ( T_RNET_IPPROTO proto, + T_RNET_DESC ** desc, + T_RV_RETURN_PATH return_path); + +/** + * Binds the connection to a local IP address and port number. + * + * @param desc Connection identifier [IN]. + * @param local_addr Local IP address + * The IP address can be specified as RNET_IP_ADDR_ANY + * in order to bind the connection to all local IP addresses [IN]. + * @param local_port If the port is not specified, the allocation of a port + * is done automatically by the system [IN]. + * @return RNET_IN_USE Another connection bound to the same address/port. + * RNET_NOT_INITIALIZED NET subsystem not initialized (internal error). + * RNET_INTERNAL_ERR Network subsystem failed. + * RNET_INVALID_PARAMETER Invalid connection ID. + * or Specified address not a valid address + * RNET_NOT_READY Still processing a callback function. + * RNET_MEMORY_ERR Not enough buffers available, too many connections. + * RNET_OK Connection successfully bound. + */ +T_RNET_RET rnet_rt_bind (T_RNET_DESC * desc, + T_RNET_IP_ADDR local_addr, + T_RNET_PORT local_port); + +/** + * Commands a connection to start listening for incoming connections. + * When an incoming connection is accepted, an RNET_ACCEPTED message is sent. + * The connection ID will have to be bound to a local port + * with the rnet_bind() function. + * + * Note that there is no accept function: After a call to listen, + * the application can receive RNET_ACCEPTED messages. + * + * @param desc Connection identifier [IN]. + * @return RNET_MEMORY_ERR No available memory for the listening connection. + * RNET_NOT_INITIALIZED NET subsystem not initialized (internal error). + * RNET_INTERNAL_ERR Network subsystem failed. + * or No more socket descriptors available. + * RNET_INVALID_PARAMETER Invalid connection ID. + * or Connection not bound with bind. + * or The ID does not support listening operation. + * RNET_IN_USE Connection already connected. + * RNET_NOT_READY Still processing a callback function. + * RNET_OK Listening successfully started. + */ +T_RNET_RET rnet_rt_listen (T_RNET_DESC *desc); + +/** + * Sets up the connection ID to connect to the remote host and sends the + * initial SYN segment which opens the connection. + * + * For the connection-oriented client (TCP), it prepares a connection from the local + * to the peer system. The connection oriented client does not need + * to call rnet_bind() before rnet_connect(), since rnet_connect() would automatically + * use the local address of the client and allocate dynamically a free local port. + * + * rnet_connect() returns immediately, does not wait for the connection to be properly setup. + * The RNET_CONNECT_CFM message is sent when the connection is established. + * If the connection could not be properly established, a RNET_ERROR_IND + * message is sent. + * + * A connectionless client (UDP) would use rnet_connect() to locally specify + * the remote server, but no connection is open. But the remote address + * is then known and does not need to be specified again. + * rnet_connect() takes as parameter a fully initialized address structure, + * specifying server address and port. + * + * @param desc Connection identifier [IN]. + * @param peer_addr Peer address [IN]. + * @param peer_port Peer port [IN]. + * @return RNET_MEMORY_ERR No buffer space available. + * RNET_NOT_INITIALIZED NET subsystem not initialized (internal error). + * RNET_INTERNAL_ERR Network subsystem failed. + * or Attempt to connect forcefully rejected. + * or Attempt to connect datagram socket to broadcast address + * RNET_INVALID_PARAMETER Invalid connection ID. + * or Remote address not a valid address (such as ADDR_ANY). + * RNET_NOT_SUPPORTED Addresses in the specified family cannot be used with this socket. + * RNET_IN_USE Already connected (connection-oriented only). + * RNET_NET_UNREACHABLE The network cannot be reached from this host at this time. + * RNET_TIMEOUT Attempt to connect timed out without establishing a connection. + * RNET_NOT_READY Still processing a callback function. + * RNET_OK Connection in progress + * RNET_CONNECT_CFM will be sent when the connection + * has been successfully completed. + */ +T_RNET_RET rnet_rt_connect (T_RNET_DESC * desc, + T_RNET_IP_ADDR peer_addr, + T_RNET_PORT peer_port); + +/** + * Enqueues the data for sending. + * + * Data is sent by enqueueing the data with a call to rnet_send(). + * The function is not-blocking. + * + * Returns RNET_PARTIAL_SENT if not all data could be sent and the function + * needs to be called again later to send the rest of the data. In that case, + * the out value of len_p is the number of bytes effectively sent. + * The remaining data can be sent when the message RNET_SEND_RDY is received. + * + * The buffer is copied by RNET, so the application can free the data buffer + * when the function returns. + * + * @param desc Connection identifier [IN]. + * @param buff Pointer on the data to send [IN]. + * @param len_p Pointer on the length of the data to send [IN]. + * Pointer on the length of the data effectively sent [OUT]. + * @return RNET_MEMORY_ERR Not enough memory is available + * RNET_NOT_INITIALIZED NET subsystem not initialized (internal error). + * RNET_INTERNAL_ERR Network subsystem failed. + * or Requested address is a broadcast address. + * RNET_INVALID_PARAMETER The connection ID is invalid. + * or The ID is not connected. + * or Invalid buff parameter. + * or Connection not bound with bind. + * RNET_CONN_ABORTED Connection broken due to the "keep-alive" activity + * detecting a failure while the operation was in progress. + * or Virtual circuit terminated due to a time-out or other failure. + * RNET_MSG_SIZE Message oriented connection (UDP), and the message + * is larger than the maximum supported by the underlying transport. + * RNET_NET_UNREACHABLE Remote host cannot be reached from this host at this time. + * RNET_CONN_RESET The virtual circuit was reset by the remote side executing a "hard" + * or "abortive" close. + * RNET_TIMEOUT The connection has been dropped, because of a + * network failure or because the system on the other end went down + * without notice. + * RNET_NOT_READY Still processing a callback function. + * RNET_OK Sending in progress + */ +T_RNET_RET rnet_rt_send (T_RNET_DESC * desc, + T_RVF_BUFFER * buff, + UINT16 * len_p); + +/** + * Read the waiting data (not-blocking). + * + * Data reception is message based: When the application receives a + * T_RNET_RECV_IND message, it can read the data with this + * rnet_recv() function. + * + * The data are copied in the buffer given by the application to RNET + * via this rnet_recv function. + * + * Datagram oriented (UDP) + * ----------------------- + * When an UDP datagram arrives, the receiver application receives + * a T_RNET_RECV_IND message. The application can then read the + * datagram with the rnet_recv function. The buffer passed to the + * function should be big enough to contain a UDP datagram, otherwise + * the message is not put in the buffer and the error code + * RNET_MSG_SIZE is returned. + * + * The OUT value of the len_p parameter can have two possible values: + * - If there was data to read and no error detected (function + * returned RNET_OK), len_p contains the size of the received datagram. + * - If there was no error, but no data to read, len_p contains 0. + * + * RNET will only send a new T_RNET_RECV_IND with a specific descriptor + * when a rnet_recv function has been called that returned a len_p parameter + * with a 0 value. Therefore, the application should loop on rnet_recv when + * it receives a T_RNET_RECV_IND message, like: + * UINT16 *len_p = -1; + * while (*len_p != 0) { + * ret = rnet_recv(desc, buff, len_p); + * ... + * } + * + * Stream oriented (TCP) + * --------------------- + * When a new stream of data arrives on a connection, the receiver + * application receives a T_RNET_RECV_IND. It can then read the flow + * with the rnet_recv function, until the len_p parameter is returned + * with a 0 value. + * + * The stack will only send a new T_RNET_RECV_IND message when + * rnet_recv has been called and has returned the len_p parameter with a 0. + * + * + * @param desc Connection identifier [IN]. + * @param buff Buffer to store the received data [OUT]. + * @param len_p Pointer on the length of the passed buffer [IN] + * Pointer on the size of the received data in the buffer [OUT]. + * @return RNET_MEMORY_ERR Not enough memory is available + * RNET_NOT_INITIALIZED NET subsystem not initialized (internal error). + * RNET_INTERNAL_ERR Network subsystem failed. + * RNET_NOT_READY Still processing a callback function. + * RNET_INVALID_PARAMETER The connection ID is invalid. + * or The ID is not connected. + * or Invalid buff parameter. + * or Connection not bound with bind. + * RNET_CONN_ABORTED Connection broken due to the "keep-alive" activity + * detecting a failure while the operation was in progress. + * or Virtual circuit terminated due to a time-out or other failure. + * RNET_MSG_SIZE The socket is message oriented (UDP), and the message + * was too large to fit into the specified buffer and was truncated. + * RNET_CONN_RESET The virtual circuit was reset by the remote side executing a "hard" + * or "abortive" close. + * RNET_TIMEOUT The connection has been dropped, because of a + * network failure or because the system on the other end went down + * without notice. + * RNET_NET_UNREACHABLE Remote host cannot be reached from this host at this time. + * RNET_OK Data successfully read. + */ +T_RNET_RET rnet_rt_recv (T_RNET_DESC * desc, + T_RVF_BUFFER *buff, + UINT16 * len_p); + +T_RNET_RET rnet_rt_recv_from (T_RNET_DESC * desc, + T_RVF_BUFFER * buff, + UINT16 * len_p, + T_RNET_IP_ADDR * from_addr, + T_RNET_PORT * from_port); + +/** + * Disables the sending on a socket and informs the peer + * about it. + * + * Subsequent calls to the send function are disallowed. + * For TCP sockets, a FIN will be sent after all data is sent and acknowledged by the receiver. + * The rnet_shutdown function does not frees the connection ID. Any resources attached + * to the ID will not be freed until rnet_close is invoked. + * + * To assure that all data is sent and received on a connection (TCP) before it + * is closed, an application should use rnet_shutdown to close connection before calling + * rnet_close. For example, to initiate a graceful disconnect: + * 1) Call rnet_shutdown. + * 2) When RNET_ERROR_IND with RNET_CONN_CLOSED is received, call rnet_recv until + * the len parameter is zero. + * 3) Call rnet_close. + * + * Following technique describes how to minimize the chance of problems + * occurring during connection teardown. In this example, the client is responsible for + * initiating a graceful shutdown. + * + * Client Side Server Side + * (1) Invoke rnet_shutdown to + * signal end of session and that + * client has no more data to send. + * (2) Receive RNET_ERROR_IND with RNET_CONN_CLOSED, + * indicating graceful shutdown in progress + * and that all data has been received. + * (3) Send any remaining response data with rnet_send. + * (5') Get RNET_RECV_IND and (4) Invoke rnet_shutdown to + * invoke rnet_recv to get any indicate server has no more data to send. + * response data sent by server. + * (5) Receive RNET_ERROR_IND (4') Invoke rnet_close. + * with RNET_CONN_CLOSED. + * (6) Invoke rnet_close. + * + * The timing sequence is maintained from step (1) to step (6) between the client and + * the server, except for step (4') and (5') which only has local timing significance in + * the sense that step (5) follows step (5') on the client side while step (4') follows + * step (4) on the server side, with no timing relationship with the remote party. + * + * @param desc Connection identifier. + * @return RNET_NOT_INITIALIZED NET subsystem not initialized (internal error). + * RNET_INTERNAL_ERR Network subsystem failed. + * RNET_INVALID_PARAMETER The connection ID is invalid. + * The descriptor is not connected (TCP only). + * RNET_NOT_READY Still processing a callback function. + * RNET_OK Connection shutdown, sending impossible + * RNET_ERROR_IND with the parameter RNET_CONN_CLOSED + * will be sent to the peer. + */ +T_RNET_RET rnet_rt_shutdown (T_RNET_DESC * desc); + +/** + * Closes the connection. + * + * Use it to release the connection ID so further references to it will fail with + * the error RNET_INVALID_PARAMETER. + * + * An application should always have a matching call to rnet_close for each successful + * call to rnet_new to return any resources to the system. + * + * The function may return RNET_MEMORY_ERR if no memory + * was available for closing the connection. If so, the application + * should wait and try again either by using the error message + * or the polling functionality. + * If the close succeeds, the function returns RNET_OK. + * + * The connection ID is deallocated after a call to rnet_close(). + * + * @param desc Connection identifier. + * @return RNET_MEMORY_ERR Not enough memory is available + * RNET_NOT_INITIALIZED NET subsystem not initialized (internal error). + * RNET_INTERNAL_ERR Network subsystem failed. + * RNET_INVALID_PARAMETER The connection ID is invalid. + * RNET_NOT_READY Still processing a callback function. + * RNET_OK Socket closed. + */ +T_RNET_RET rnet_rt_close (T_RNET_DESC * desc); + +/** + * Gets the local address and port of a connection ID. + * + * @param desc Connection identifier [IN]. + * @param local_addr_p Local IP address [OUT]. + * @param local_port_p Local port [OUT]. + * @return RNET_NOT_INITIALIZED NET subsystem not initialized (internal error). + * RNET_INTERNAL_ERR Network subsystem failed. + * RNET_INVALID_PARAMETER The connection ID is invalid. + * or Not bound to an address with bind. + * or ADDR_ANY is specified in bind but connection not yet occurred. + * RNET_NOT_READY Still processing a callback function. + * RNET_OK Local address/port successfully get. + */ +T_RNET_RET rnet_rt_get_local_addr_port (T_RNET_DESC * desc, + T_RNET_IP_ADDR * local_addr_p, + T_RNET_PORT * local_port_p); + +/** + * Use to determine the amount of data pending in the network's input buffer + * that can be read from the connection ID. + * + * If desc is stream oriented (TCP), returns the amount of data that can be read + * in a single call to the rnet_recv function; this might not be the same as the + * total amount of data queued on the socket. + * If desc is message oriented (UDP), returns the size of the first datagram + * (message) queued on the socket. + * + * @param desc Connection identifier [IN]. + * @param size_p Pointer to an unsigned int in which the result is stored [OUT]. + * @return RNET_NOT_INITIALIZED NET subsystem not initialized (internal error). + * RNET_INTERNAL_ERR Network subsystem failed. + * RNET_INVALID_PARAMETER The connection ID is invalid. + * RNET_NOT_READY Still processing a callback function. + * RNET_OK Value successfully get. + */ +T_RNET_RET rnet_rt_get_buff_size (T_RNET_DESC * desc, + UINT32 * size_p); + +/** + * Requests host information corresponding to a host name or to a + * network address. + * + * One of the two parameters name or addr must be NULL. + * + * This function is bridge function sending a corresponding message to RNET. + * The message RNET_HOST_INFO is sent back when the requested information + * is available. + * + * Note that this function does not need a connection identifier and specifies + * its own return path. + * + * @param name Name of the host to resolve [IN]. + * @param addr Network address [IN]. + * @param return_path Return path for sending the response. + * @param user_data Pointer on some user-defined data that + * will be contained in the RNET_HOST_INFO message [IN]. + * @return RNET_MEMORY_ERR Not enough memory is available. + * RNET_OK The message could be correctly send. + */ +T_RNET_RET rnet_rt_get_host_info (char *name, + T_RNET_IP_ADDR addr, + T_RV_RETURN_PATH return_path, + void * user_data); + +/* + * Following functions are not directly part of the networking API, + * but they are used to retrieve some simple information from a connection + * descriptor. They are simple blocking functions, not sending any messages. + */ + +/** + * Retrieves the protocol associated to a connection descriptor. + * + * @param desc Connection identifier. + * @return A value of the T_RNET_IPPROTO enumeration. + */ +T_RNET_IPPROTO rnet_rt_get_proto (T_RNET_DESC *desc); + +/** + * Associates an application specific pointer to a connection ID. + * + * @param desc Connection identifier. + * @param user_data Pointer that can be used by an application to store + * application specific data. + */ +void rnet_rt_set_user_data (T_RNET_DESC *desc, void *user_data); + +/** + * Returns the application specific pointer associated to the connection ID. + * + * @param desc Connection identifier. + * @return Application specific data. + */ +void * rnet_rt_get_user_data (T_RNET_DESC *desc); +/*@}*/ + +/** + * Gets the maximum send size of a message. + * + * @param desc Connection identifier [IN]. + * @param size_p Maximum send size [OUT]. + * @return RNET_NOT_INITIALIZED NET subsystem not initialized (internal error). + * RNET_INTERNAL_ERR Network subsystem failed. + * RNET_INVALID_PARAMETER The connection ID is invalid. + * RNET_NOT_READY Still processing a callback function. + * RNET_OK Local address/port successfully get. + */ + +T_RNET_RET rnet_rt_get_max_packet_size (T_RNET_DESC *desc, + UINT32 *size_p); + +/** + * NexGenIP specific API + */ + +T_RNET_RET rnet_rt_route_add( T_RNET_IP_ADDR dest, T_RNET_IP_ADDR netmask, T_RNET_IP_ADDR gateway); +T_RNET_RET rnet_rt_route_del( T_RNET_IP_ADDR dest); +T_RNET_RET rnet_rt_route_default( T_RNET_IP_ADDR gateway); + +T_RNET_RET rnet_rt_if_setaddr( const char *ifname, T_RNET_IP_ADDR addr, T_RNET_IP_ADDR netmask); +T_RNET_RET rnet_rt_if_getaddr( const char *ifname, T_RNET_IP_ADDR *addr, T_RNET_IP_ADDR *netmask); +T_RNET_RET rnet_rt_if_setdstaddr( const char *ifname, T_RNET_IP_ADDR dstaddr); +T_RNET_RET rnet_rt_if_getdstaddr( const char *ifname, T_RNET_IP_ADDR *dstaddr); + +T_RNET_RET rnet_rt_set_resolver( const char *domain, T_RNET_IP_ADDR dns1, T_RNET_IP_ADDR dns2); + +#ifdef __cplusplus +} +#endif + +#endif /*__RNET_RT_API_H_*/ + +#endif /* ifdef RNET_CFG_REAL_TRANSPORT */ +