tini400_dns.h

tini的http-slientC程序

/*---------------------------------------------------------------------------
 *  Copyright (C) 2003, 2004 Dallas Semiconductor Corporation, 
 *  All Rights Reserved.
 * 
 *  Permission is hereby granted, free of charge, to any person obtaining a
 *  copy of this software and associated documentation files (the "Software"),
 *  to deal in the Software without restriction, including without limitation
 *  the rights to use, copy, modify, merge, publish, distribute, sublicense,
 *  and/or sell copies of the Software, and to permit persons to whom the
 *  Software is furnished to do so, subject to the following conditions:
 * 
 *  The above copyright notice and this permission notice shall be included
 *  in all copies or substantial portions of the Software.
 * 
 *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 *  OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 *  MERCHANTABILITY,  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 *  IN NO EVENT SHALL DALLAS SEMICONDUCTOR BE LIABLE FOR ANY CLAIM, DAMAGES
 *  OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 *  ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 *  OTHER DEALINGS IN THE SOFTWARE.
 * 
 *  Except as contained in this notice, the name of Dallas Semiconductor
 *  shall not be used except as stated in the Dallas Semiconductor
 *  Branding Policy.
 * ---------------------------------------------------------------------------
 *
 * This file contains function definitions for DNS client code to be used
 * with the Dallas Semiconductor 400 processor.  This file is intended for use 
 * with the Keil MicroVision (uVision) C compiler.
 *
 * ---------------------------------------------------------------------------
 */
#ifndef __tini400_dns_
#define __tini400_dns_

#include <stdlib.h>               // needed for size_t

/** \file tini400_dns.h
 *  \brief DNS Client functions for the DS80C400 ROM
 *
 *  This libarary contains functions for resolving a host name to an 
 *  IP address that is usable by the silicon software for making
 *  socket function calls.  Note that the functions in
 *  this library are not safe to be called from multiple processes at
 *  the same time.  The functions in this library store their results
 *  in static memory locations, and must be retrieved and stored in
 *  alternate locations before further DNS operations are performed.
 *
 *  Note that as of version 3, this library has been changed to use
 *  the system-wide DNS server entries, which might be set by the
 *  DHCP client (from data recieved in a DHCP response).  Applications
 *  can make sure they have a valid server entry by making sure the
 *  DNS server IP addresses are not all 0's, since the ROM 
 *  initialization functions clear the DNS server entries.
 *  
 *  For detailed information on the DS80C400 please see the
 *  <a href="http://pdfserv.maxim-ic.com/arpdf/Design/DS80C400UG.pdf">
 *  High-Speed Microcontroller User's Guide: DS80C400 Supplement</a>.
 *
 *  \warning  The functions in this library are <b>NOT</b> multi-process 
 *            safe--that is, if you call the same method from two different 
 *            processes at the same time, the parameters to the function 
 *            may be destroyed, yielding unpredictable results.
 *
 *  \warning  The functions in this library use String functions such as
 *            <b>sprintf</b> for data formatting, which are not 
 *            multiprocess safe.  Care must be taken that DNS functions do
 *            not operate at the same time as other string formatting 
 *            operations.
 */

/** Version number associated with this header file.  Should be the same as
 * the version number returned by the <i>#dns_version</i> function.
 * \sa #dns_version */
#define TINI400_DNS_VERSION    5

/**
 * Structure for host information that will be returned by the DNS client
 * functions.
 */
struct hostent
{
    char*  h_name;      ///< String with the official name of the host
    char** h_aliases;   ///< String with alternative host names
    int    h_addrtype;  ///< Address type (<i>#AF_INET</i> or <i>#AF_INET6</i>)
    int    h_length;    ///< Length of the address
    char** h_addr_list; ///< List of network addresses, each of <i>#h_length</i> bytes.  The list is null-terminated.
};

/**
 * Structure for host information requested with an MX record type.
 *
 * \sa #dns_getmx
 */
struct mailhostent
{
    char*  h_name;     ///< String with the name of a mail host.
    int    preference; ///< Preference value reported by the DNS query.
};



/**
 * \brief    Looks up information on a host given an IP address.
 *
 * Contacts a DNS server and attempts to find known host names for the given
 * IP address.
 *
 * \param    addr IP address structure, either <i>#in_addr</i> or <i>#in6_addr</i>
 * \param    len The length of the input structure passed to <i>addr</i> (4 or 16)
 * \param    type <i>#AF_INET</i> or <i>#AF_INET6</i>
 *
 * \return   Host structure with any names found, or <i>NULL</i> if the 
 *           operation failed.
 *
 * \sa       #AF_INET
 * \sa       #AF_INET6
 * \sa       #in_addr
 * \sa       #in6_addr
 * \sa       #gethostbyname
 * \sa       #inet_addr
 * \sa       #hostent
 */
//---------------------------------------------------------------------------
struct hostent* gethostbyaddr(void* addr, size_t len, int type);

/**
 * \brief    Looks up information on a host given a host name.
 *
 * Contacts a DNS server and attempts to find known IP addresses given a
 * host name.
 *
 * \param    name    String representing the host name
 *
 * \return   Host structure with any names found, or <i>NULL</i> if the 
 *           operation failed.
 *
 * \sa       #gethostbyaddr
 * \sa       #hostent
 */
//---------------------------------------------------------------------------
struct hostent* gethostbyname(char* name);

/**
 * \brief    Initializes the DNS client code.
 *
 * Performs initialization for the DNS client.  This function need only be
 * called once at the start of the application.
 *
 */
//---------------------------------------------------------------------------
void dns_init(void);

/**
 * \brief    Sets the socket timeout value used for DNS server communications.
 *
 * Sets the timeout value applied to all sockets that communicate with the
 * DNS server.  Call this function to make sure DNS operations fail after
 * a reasonable waiting time.  All DNS operations are retried up to 4 times.
 *
 * \param    t    Global timeout value for sockets use in DNS server 
 *                communications
 *
 * \sa       #dns_gettimeout
 */
//---------------------------------------------------------------------------
void dns_settimeout(unsigned long t);

/**
 * \brief    Gets the socket timeout value used for DNS server communications.
 *
 * Gets the timeout value applied to all sockets that communicate with the
 * DNS server.  Call this function to verify the timeout used by DNS socket 
 * operations.
 *
 * \return   Global timeout value for sockets use in DNS server communications
 *
 * \sa       #dns_settimeout
 */
//---------------------------------------------------------------------------
unsigned long dns_gettimeout(void);

/**
 * \brief    Gets the address of the primary DNS server.
 *
 * Fills in an address structure with the IP of the secondary DNS server 
 * used by this DNS client code.  DNS operations first try to use a server 
 * designated as primary, and the use a server designated as secondary if
 * the primary fails to return results.  
 *
 * Note that this gets the system's primary DNS server setting.  This may 
 * have been set by the DHCP client or by previous calls to 
 * <i>#dns_setprimary</i>.  This function is equivalent to 
 * <i>#dhcp_getprimarydns</i>.
 *
 * \param    sa  will be filled in with the address of the primary DNS server
 *
 * \sa       #dns_setprimary
 * \sa       #dns_setsecondary
 * \sa       #dns_getsecondary
 * \sa       #dhcp_getprimarydns
 */
//---------------------------------------------------------------------------
void dns_getprimary(struct sockaddr* sa);

/**
 * \brief    Sets the address of the primary DNS server.
 *
 * Sets the address of the primary DNS server used by this DNS client code.  
 * DNS operations first try to use a server designated as primary, and the 
 * use a server designated as secondary if the primary fails to return results.
 *
 * Note that this sets the system's primary DNS server setting.  If the 
 * system's primary DNS server entry had been previously set by the DHCP
 * client, that information will be destroyed by this function.
 *
 * \param    sa   address of primary DNS server
 *
 * \sa       #dns_getprimary
 * \sa       #dns_setsecondary
 * \sa       #dns_getsecondary
 */
//---------------------------------------------------------------------------
void dns_setprimary(struct sockaddr* sa);

/**
 * \brief    Gets the address of the secondary DNS server.
 *
 * Fills in an address structure with the IP of the secondary DNS server 
 * used by this DNS client code.  DNS operations first try to use a server 
 * designated as primary, and the use a server designated as secondary if
 * the primary fails to return results.  
 *
 * Note that this gets the system's secondary DNS server setting.  This may 
 * have been set by the DHCP client or by previous calls to 
 * <i>#dns_setsecondary</i>.  This function is equivalent to 
 * <i>#dhcp_getsecondarydns</i>.
 *
 * \param    sa   will be filled in with the address of the secondary DNS 
 *                server
 *
 * \sa       #dns_setprimary
 * \sa       #dns_getprimary
 * \sa       #dns_setsecondary
 * \sa       #dhcp_getsecondarydns
 */
//---------------------------------------------------------------------------
void dns_getsecondary(struct sockaddr* sa);

/**
 * \brief    Sets the address of the secondary DNS server.
 *
 * Sets the address of the secondary DNS server used by this DNS client code.  
 * DNS operations first try to use a server designated as primary, and the 
 * use a server designated as secondary if the primary fails to return results.
 *
 * Note that this sets the system's secondary DNS server setting.  If the 
 * system's secondary DNS server entry had been previously set by the DHCP
 * client, that information will be destroyed by this function.
 *
 * \param    sa   address of secondary DNS server
 *
 * \sa       #dns_getprimary
 * \sa       #dns_setprimary
 * \sa       #dns_getsecondary
 */
//---------------------------------------------------------------------------
void dns_setsecondary(struct sockaddr* sa);




/**
 * \brief        Performs a DNS MX record lookup.
 *
 * MX records are mail exchanger records. In order to send an email
 * without using a mail relay (mail host), you need to look up the
 * MX record of the remote domain and then open the SMTP connection
 * to the address returned by dns_getmx().
 *
 * \param name domain to look up.
 *
 * \return DNS response(s) or NULL for failed lookup.  If any valid data is
 *         returned, the first invalid <i>#mailhostent</i> entry will have 
 *         <code>NULL</code> for a host name. 
 *
 * \sa     #mailhostent
 */
//---------------------------------------------------------------------------
struct mailhostent* dns_getmx(char* name);


/**
 * \brief    Enables/disables attempts to make IPv6 DNS queries.
 *
 * Use an <i>enable</i> value of 0 to disable attempts to perform
 * IPv6 queries.  Diabling IPv6 queries can dramatically increase 
 * the speed of the library routines.  Use an <i>enable</i> value of
 * non-zero to enable IPv6 DNS queries. 
 *
 * \param    enable   0 to disable IPv6 DNS queries, non-zero to enable
 */
//---------------------------------------------------------------------------
void dns_enableipv6queries(unsigned char enable);


/**
 * \brief     Returns the version number of this DNS client library.
 *
 * \return    Version number of this DNS client library.
 */
//---------------------------------------------------------------------------
unsigned int dns_version();

#endif