rom400_sock.h

tini的http-slientC程序

 *            a call to <i>#syn_setDatagramAddress</i>.
 *
 * Sends a UDP datagram to an address earlier specified by a call to
 * <i>#syn_setDatagramAddress</i>.  The success/failure code 
 * this function returns says nothing of if the packet was recieved by the 
 * target, only that the socket layer was able to push the data out.  The 
 * socket <i>socket_num</i> must have been created with a type 
 * <i>#SOCKET_TYPE_DATAGRAM</i>.
 * 
 * \param     socket_num      the socket handle to use to send a UDP packet
 * \param     length          the number of bytes to send in the datagram packet
 * \param     buffer          the data to send in the datagram packet
 *
 * \return    0 for success, non-zero for failure.
 *
 * \sa        #syn_recvfrom
 * \sa        #syn_socket
 * \sa        #syn_setDatagramAddress
 */
//---------------------------------------------------------------------------
int  syn_sendto(int socket_num, unsigned int length, void* buffer);

/**
 * \brief     Receive a UDP datagram.
 *
 * Receives a message on the specified socket, and stores the address that 
 * sent it in the address structure set by an earlier call to 
 * <i>#syn_setDatagramAddress</i>.  If no data is available,
 * <i>#syn_recvfrom</i> blocks subject to the <i>#SO_TIMEOUT</i> value.  The socket
 * <i>socket_num</i> must have been created with a type
 * <i>#SOCKET_TYPE_DATAGRAM</i>.  It is required to use <i>#syn_bind</i> to assign a 
 * local port to the socket, before receiving data.
 * <b>NOTE:</b> This function reads <b>up to</b> <i>length</i> bytes of a 
 * datagram. Any data not read in the datagram will be discarded.
 * 
 * \param     socket_num      the socket handle to use to wait for and read a UDP packet
 * \param     length          the maximum number of bytes to read from a datagram socket
 * \param     buffer          the location to write any data read from the datagram socket
 *
 * \return    The number of bytes read.  If the operation times out according
 *            to the <i>SO_TIMEOUT</i>, a value of -2 is returned.  If another
 *            error occurs, -1 is returned.
 *
 * \sa        #syn_sendto
 * \sa        #syn_socket
 * \sa        #syn_bind
 */
//---------------------------------------------------------------------------
int  syn_recvfrom(int socket_num, unsigned int length, void* buffer);

/**
 * \brief     Connects a TCP socket to a specified address.
 *
 * Connects to a specified address with a streaming socket.  This function can 
 * only be used once with each socket.  The socket <i>socket_num</i> must have 
 * been created with type <i>#SOCKET_TYPE_STREAM</i>.
 *
 * \param     socket_num      the socket handle to use to wait for and read a UDP packet
 * \param     address         IP address and port number to create a streaming connection to
 *
 * \return    0 for success, non-zero for failure.
 *
 * \sa        #socket
 */
//---------------------------------------------------------------------------
int  syn_connect(int socket_num, struct sockaddr* address);

/**
 * \brief     Binds a socket to a specified address.
 *
 * Assigns a local address and port (stored in the <i>address</i> parameter)
 * to a socket.  Binding a socket is necessary for server sockets.  For
 * client sockets, use <i>#bind</i> if a specific source port is desirable.
 *
 * Fill <i>address</I> with 0's (for sin_addr and sin_port) to bind to
 * any available local port.  Use <i>#getsockname</i> to discover 
 * which port the socket was bound to.
 *
 * <b>NOTE:</b> When binding a UDP socket, matching inbound UDP packets will
 * be queued up for the socket. Call <i>#recvfrom</i> periodically to avoid
 * the risk of running out of kernel memory.
 *
 * \param     socket_num      socket handle to bind to a local port number
 * \param     address         contains the local address (including port number)
 *
 * \return    0 for success, non-zero for failure.
 *
 * \sa        #listen
 * \sa        #getsockname
 * \sa        #recvfrom
 */
//---------------------------------------------------------------------------
int  syn_bind(int socket_num, struct sockaddr* address);

/**
 * \brief     Tells a socket to listen for incoming connections.
 *
 * Tells the socket to listen for connections.  A queue of length <i>backlog</i>
 * is created for pending (un-<i>#accept</i>ed connections).  It is required to 
 * use <i>#bind</i> to assign a local port before calling <i>#listen</i>.  Use
 * <i>#accept</i> to move an incoming request to an established state, or wait
 * for incoming connections.
 *
 * \param     socket_num  socket handle that will listen for connections
 * \param     backlog     the maximum number of pending connections (max 16
 *                        for the DS80C400)
 *
 * \return    0 for success, non-zero for failure.
 *
 * \sa        #bind
 * \sa        #accept
 */
//---------------------------------------------------------------------------
int  syn_listen(int socket_num, unsigned int backlog);

/**
 * \brief     Accepts TCP connections on the specified socket.
 * 
 * Accepts a TCP conection on the specified socket.  This function moves
 * the first pending connection request from the listen queue into the
 * established state, assigning a new local socket to the connection
 * for communication.  <i>#accept</i> blocks if there are no pending
 * incoming requests.  The socket <i>socket_num</i> must have been created 
 * with type <i>#SOCKET_TYPE_STREAM</i>, bound to an address using <i>#bind</i>, 
 * and given a listen queue by calling <i>#listen</i>.
 *
 * \param     socket_num      the handle of the socket that will wait for connections
 * \param     address         location to write remote address
 *
 * \return    New socket handle for communicating with remote 
 *            socket, or -1 for failure
 *
 * \sa        #socket
 * \sa        #bind
 * \sa        #listen
 */
//---------------------------------------------------------------------------
int  syn_accept(int socket_num, struct sockaddr* address);

/**
 * \brief     Reads data from a TCP socket.
 *
 * Reads data from a TCP socket.  If there is no data available, <i>#recv</i>
 * blocks until there is data, subject to the value of <i>#SO_TIMEOUT</i>.
 * <b>NOTE:</b> This function reads <b>up to</b> <i>length</i> bytes. Call this function
 * repeatedly if you need to read a minimum number of bytes.
 *
 * \param     socket_num  handle of the streaming socket that will read data
 * \param     length      maximum amount of data to read
 * \param     buffer      location to write any data read
 *
 * \return    The number of bytes read.  If the operation times out according
 *            to the <i>SO_TIMEOUT</i>, a value of -2 is returned.  If another
 *            error occurs, -1 is returned.  If the socket was closed by the 
 *            other side, 0 is returned.
 *
 * \sa        #connect
 * \sa        #send
 */
//---------------------------------------------------------------------------
int  syn_recv(int socket_num, unsigned int length, void* buffer);

/**
 * \brief     Sends data to a TCP socket.
 *
 * Writes data to a TCP socket.  The return value of this function is only a 
 * local success/failure code, and may not necessarily detect transmission 
 * errors.
 *
 * \param     socket_num  handle of the streaming socket that will write data
 * \param     length      number of bytes to write
 * \param     buffer      location of data to write
 *
 * \return    0 for success, non-zero for failure.
 *
 * \sa        #connect
 * \sa        #recv
 */
//---------------------------------------------------------------------------
int  syn_send(int socket_num, unsigned int length, void* buffer);

/**
 * \brief     Get various socket options.
 *
 * Reads a number of supported socket options.  Data written into the
 * buffer depends on the requested socket option.
 *
 * <table>
 *   <tr> <td> <b>Name</b> </td> <td> <b>Description</b> </td> <td> <b>Data in buffer</b> </td> </tr>
 *   <tr> <td> TCP_NODELAY </td> <td> TCP Nagle Enable   </td> <td> 1 byte                </td> </tr>
 *   <tr> <td> SO_LINGER   </td> <td> Ignored            </td> <td> N/A                   </td> </tr>
 *   <tr> <td> SO_TIMEOUT  </td> <td> Inactivity timeout </td> <td> 4 bytes (milliseconds, MSB first) </td> </tr>
 *   <tr> <td> SO_BINDADDR </td> <td> Local socket IP    </td> <td> 16 bytes              </td> </tr>
 * </table>
 *
 * This function assumes there is enough room in <i>buffer</i> to store
 * the requested data.
 *
 * \param     socket_num  socket to get option information for
 * \param     name        option to get
 * \param     buffer      location where option data will be written
 *
 * \return    0 for success, non-zero for failure
 *
 * \sa        #setsockopt
 */
//---------------------------------------------------------------------------
int  syn_getsockopt(int socket_num, unsigned int name, void* buffer);

/**
 * \brief     Set various socket options.
 *
 * Sets a number of supported socket options.  Input data in the
 * buffer depends on the desired socket option.
 *
 * <table>
 *   <tr> <td> <b>Name</b> </td> <td> <b>Description</b> </td> <td> <b>Data in buffer</b> </td> </tr>
 *   <tr> <td> TCP_NODELAY </td> <td> TCP Nagle Enable   </td> <td> 1 byte                </td> </tr>
 *   <tr> <td> SO_LINGER   </td> <td> Ignored            </td> <td> N/A                   </td> </tr>
 *   <tr> <td> SO_TIMEOUT  </td> <td> Inactivity timeout </td> <td> 4 bytes (milliseconds, MSB first) </td> </tr>
 *   <tr> <td> SO_BINDADDR </td> <td> Read only          </td> <td> N/A                   </td> </tr>
 * </table>
 *
 * \param     socket_num  socket to set option information for
 * \param     name        option to set
 * \param     buffer      location of option data that will be written
 *
 * \return    0 for success, non-zero for failure
 *
 * \sa        #getsockopt
 */
//---------------------------------------------------------------------------
int  syn_setsockopt(int socket_num, unsigned int name, void* buffer);

/**
 * \brief     Gets the local IP and port of a socket.
 *
 * Stores the local IP and port number of the specified socket in the
 * the <i>address</i> parameter.  Use <i>#getpeername</i> to get
 * the remote port's information for a connection-based (TCP) 
 * socket.
 * 
 * \param     socket_num      handle of the socket to get local IP and port for
 * \param     address         structure where IP and port will be stored
 *
 * \return    0 for success, non-zero for failure
 *
 * \sa        #getpeername
 */
//---------------------------------------------------------------------------
int  syn_getsockname(int socket_num, struct sockaddr* address);

/**
 * \brief     Gets the remote address of a connection-based (TCP socket).
 *
 * Stores the IP address of the remote socket communicating with the socket
 * specified by <i>socket_num</i>.  Use <i>#getsockname</i> to get the local
 * port's information.
 *
 * \param     socket_num      handle of the socket to get remote IP and port for
 * \param     address         structure where IP and port will be stored
 *
 * \return    0 for success, non-zero for failure
 *
 * \sa        #getsockname
 */
//---------------------------------------------------------------------------
int  syn_getpeername(int socket_num, struct sockaddr* address);

/**
 * \brief     Close all sockets associated with a task.
 *
 * Close all sockets associtaed with a process ID.  User applications should
 * call this function whenever a task dies or is killed to ensure all
 * associated resources are freed by the socket layer.
 * 
 * \warning   The DS80C400 Silicon Software task scheduler does <b>NOT</b>
 *            call this function.  User applications should call <i>#cleanup</i> 
 *            after each call to <i>#task_kill</i>.
 *
 * \param     process_id   Task PID to clean up sockets associated with
 *
 * \return    0 for success, non-zero for failure.
 */
//---------------------------------------------------------------------------
int  syn_cleanup(unsigned int process_id);

/**
 * \brief     Reports number of bytes available on a TCP socket.
 *
 * Reports the number of bytes available on a TCP socket.  This is the number
 * of bytes that can currently be read using the <i>#recv</i> function without
 * blocking.
 *
 * \param     socket_num  the handle of the socket to check for available data
 *
 * \return    The number of bytes available for a <i>#recv</i> function call on this
 *            socket, or -1 on failure.
 *
 * \sa        #recv
 */
//---------------------------------------------------------------------------
int  syn_avail(int socket_num);

/**
 * \brief     Adds a socket to a specified multicast group.
 *
 * Adds a UDP socket to a specified multicast group.  In order to receive
 * multicasts from a group, first <i>#bind</i> the socket to the port number
 * that the multicast group is using (it is not sufficient to include it
 * here in order to receive).
 *
 * Use the <i>#leave</i> function to leave a multicast group.
 *
 * \warning   IPv6 multicasting is not supported
 *
 * \param     socket_num      handle for the datagram socket that will join a multicast group
 * \param     address         IP address of the multicast group to join
 *
 * \return    0 for success, non-zero for failure.
 *
 * \sa        #leave
 */
//---------------------------------------------------------------------------
int  syn_join(int socket_num, struct sockaddr* address);

/**