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 //! Synchronous DNS Resolution
  12 //!
  13 //! Contains the functionality to perform DNS resolution or reverse lookup,
  14 //! in a style related to `getaddrinfo()` and `getnameinfo()`, respectively.
  15
  16 #![allow(missing_docs)]
  17
  18 pub use self::SocketType::*;
  19 pub use self::Flag::*;
  20 pub use self::Protocol::*;
  21
  22 use iter::IteratorExt;
  23 use io::{IoResult};
  24 use io::net::ip::{SocketAddr, IpAddr};
  25 use option::Option;
  26 use option::Option::{Some, None};
  27 use string::String;
  28 use sys;
  29 use vec::Vec;
  30
  31 /// Hints to the types of sockets that are desired when looking up hosts
  32 #[deriving(Copy)]
  33 pub enum SocketType {
  34     Stream, Datagram, Raw
  35 }
  36
  37 /// Flags which can be or'd into the `flags` field of a `Hint`. These are used
  38 /// to manipulate how a query is performed.
  39 ///
  40 /// The meaning of each of these flags can be found with `man -s 3 getaddrinfo`
  41 #[deriving(Copy)]
  42 pub enum Flag {
  43     AddrConfig,
  44     All,
  45     CanonName,
  46     NumericHost,
  47     NumericServ,
  48     Passive,
  49     V4Mapped,
  50 }
  51
  52 /// A transport protocol associated with either a hint or a return value of
  53 /// `lookup`
  54 #[deriving(Copy)]
  55 pub enum Protocol {
  56     TCP, UDP
  57 }
  58
  59 /// This structure is used to provide hints when fetching addresses for a
  60 /// remote host to control how the lookup is performed.
  61 ///
  62 /// For details on these fields, see their corresponding definitions via
  63 /// `man -s 3 getaddrinfo`
  64 #[deriving(Copy)]
  65 pub struct Hint {
  66     pub family: uint,
  67     pub socktype: Option<SocketType>,
  68     pub protocol: Option<Protocol>,
  69     pub flags: uint,
  70 }
  71
  72 #[deriving(Copy)]
  73 pub struct Info {
  74     pub address: SocketAddr,
  75     pub family: uint,
  76     pub socktype: Option<SocketType>,
  77     pub protocol: Option<Protocol>,
  78     pub flags: uint,
  79 }
  80
  81 /// Easy name resolution. Given a hostname, returns the list of IP addresses for
  82 /// that hostname.
  83 pub fn get_host_addresses(host: &str) -> IoResult<Vec<IpAddr>> {
  84     lookup(Some(host), None, None).map(|a| a.into_iter().map(|i| i.address.ip).collect())
  85 }
  86
  87 /// Reverse name resolution. Given an address, returns the corresponding
  88 /// hostname.
  89 pub fn get_address_name(addr: IpAddr) -> IoResult<String> {
  90     sys::addrinfo::get_address_name(addr)
  91 }
  92
  93 /// Full-fledged resolution. This function will perform a synchronous call to
  94 /// getaddrinfo, controlled by the parameters
  95 ///
  96 /// # Arguments
  97 ///
  98 /// * hostname - an optional hostname to lookup against
  99 /// * servname - an optional service name, listed in the system services
 100 /// * hint - see the hint structure, and "man -s 3 getaddrinfo", for how this
 101 ///          controls lookup
 102 ///
 103 /// FIXME: this is not public because the `Hint` structure is not ready for public
 104 ///      consumption just yet.
 105 #[allow(unused_variables)]
 106 fn lookup(hostname: Option<&str>, servname: Option<&str>, hint: Option<Hint>)
 107           -> IoResult<Vec<Info>> {
 108     sys::addrinfo::get_host_addresses(hostname, servname, hint)
 109 }
 110
 111 // Ignored on android since we cannot give tcp/ip
 112 // permission without help of apk
 113 #[cfg(all(test, not(target_os = "android")))]
 114 mod test {
 115     use prelude::v1::*;
 116     use super::*;
 117     use io::net::ip::*;
 118
 119     #[test]
 120     fn dns_smoke_test() {
 121         let ipaddrs = get_host_addresses("localhost").unwrap();
 122         let mut found_local = false;
 123         let local_addr = &Ipv4Addr(127, 0, 0, 1);
 124         for addr in ipaddrs.iter() {
 125             found_local = found_local || addr == local_addr;
 126         }
 127         assert!(found_local);
 128     }
 129
 130     #[ignore]
 131     #[test]
 132     fn issue_10663() {
 133         // Something should happen here, but this certainly shouldn't cause
 134         // everything to die. The actual outcome we don't care too much about.
 135         get_host_addresses("example.com").unwrap();
 136     }
 137 }