src/libstd/io/net/addrinfo.rs

   1 // Copyright 2013 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 /*!
  12
  13 Synchronous DNS Resolution
  14
  15 Contains the functionality to perform DNS resolution in a style related to
  16 getaddrinfo()
  17
  18 */
  19
  20 #![allow(missing_doc)]
  21
  22 use io::IoResult;
  23 use io::net::ip::{SocketAddr, IpAddr};
  24 use option::{Option, Some, None};
  25 use rt::rtio::{IoFactory, LocalIo};
  26 use slice::ImmutableVector;
  27
  28 /// Hints to the types of sockets that are desired when looking up hosts
  29 pub enum SocketType {
  30     Stream, Datagram, Raw
  31 }
  32
  33 /// Flags which can be or'd into the `flags` field of a `Hint`. These are used
  34 /// to manipulate how a query is performed.
  35 ///
  36 /// The meaning of each of these flags can be found with `man -s 3 getaddrinfo`
  37 pub enum Flag {
  38     AddrConfig,
  39     All,
  40     CanonName,
  41     NumericHost,
  42     NumericServ,
  43     Passive,
  44     V4Mapped,
  45 }
  46
  47 /// A transport protocol associated with either a hint or a return value of
  48 /// `lookup`
  49 pub enum Protocol {
  50     TCP, UDP
  51 }
  52
  53 /// This structure is used to provide hints when fetching addresses for a
  54 /// remote host to control how the lookup is performed.
  55 ///
  56 /// For details on these fields, see their corresponding definitions via
  57 /// `man -s 3 getaddrinfo`
  58 pub struct Hint {
  59     family: uint,
  60     socktype: Option<SocketType>,
  61     protocol: Option<Protocol>,
  62     flags: uint,
  63 }
  64
  65 pub struct Info {
  66     address: SocketAddr,
  67     family: uint,
  68     socktype: Option<SocketType>,
  69     protocol: Option<Protocol>,
  70     flags: uint,
  71 }
  72
  73 /// Easy name resolution. Given a hostname, returns the list of IP addresses for
  74 /// that hostname.
  75 pub fn get_host_addresses(host: &str) -> IoResult<~[IpAddr]> {
  76     lookup(Some(host), None, None).map(|a| a.map(|i| i.address.ip))
  77 }
  78
  79 /// Full-fleged resolution. This function will perform a synchronous call to
  80 /// getaddrinfo, controlled by the parameters
  81 ///
  82 /// # Arguments
  83 ///
  84 /// * hostname - an optional hostname to lookup against
  85 /// * servname - an optional service name, listed in the system services
  86 /// * hint - see the hint structure, and "man -s 3 getaddrinfo", for how this
  87 ///          controls lookup
  88 ///
  89 /// FIXME: this is not public because the `Hint` structure is not ready for public
  90 ///      consumption just yet.
  91 fn lookup(hostname: Option<&str>, servname: Option<&str>, hint: Option<Hint>)
  92           -> IoResult<~[Info]> {
  93     LocalIo::maybe_raise(|io| io.get_host_addresses(hostname, servname, hint))
  94 }
  95
  96 // Ignored on android since we cannot give tcp/ip
  97 // permission without help of apk
  98 #[cfg(test, not(target_os = "android"))]
  99 mod test {
 100     iotest!(fn dns_smoke_test() {
 101         let ipaddrs = get_host_addresses("localhost").unwrap();
 102         let mut found_local = false;
 103         let local_addr = &Ipv4Addr(127, 0, 0, 1);
 104         for addr in ipaddrs.iter() {
 105             found_local = found_local || addr == local_addr;
 106         }
 107         assert!(found_local);
 108     })
 109
 110     iotest!(fn issue_10663() {
 111         // Something should happen here, but this certainly shouldn't cause
 112         // everything to die. The actual outcome we don't care too much about.
 113         get_host_addresses("example.com").unwrap();
 114     } #[ignore])
 115 }