// -*- Mode: C++; indent-tabs-mode: nil; c-basic-offset: 2 -*- /* Copyright (C) 2009 jonathon jongsma * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, write to the Free * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ #include #include #include #include #include _DEFS(giomm,gio) _PINCLUDE(glibmm/private/object_p.h) namespace Gio { /** Asynchronous and cancellable DNS resolver * * Resolver provides cancellable synchronous and asynchronous DNS resolution, * for hostnames (lookup_by_address(), lookup_by_name() and their async * variants) and SRV (service) records (lookup_service()). * * NetworkAddress and NetworkService provide wrappers around Resolver * functionality that also implement SocketConnectable, making it easy to * connect to a remote host/service. * * @newin{2,24} * @ingroup NetworkIO */ class Resolver : public Glib::Object { _CLASS_GOBJECT(Resolver, GResolver, G_RESOLVER, Glib::Object, GObject) protected: public: static Glib::RefPtr get_default(); _IGNORE(g_resolver_get_default) static void set_default(const Glib::RefPtr& resolver); _IGNORE(g_resolver_set_default) // g_resolver_free_addresses is just a C convenience function _IGNORE(g_resolver_free_addresses) #m4 _CONVERSION(`GList*',`Glib::ListHandle< Glib::RefPtr >',`$2($3, Glib::OWNERSHIP_DEEP)') _WRAP_METHOD(Glib::ListHandle< Glib::RefPtr > lookup_by_name(const Glib::ustring& hostname, const Glib::RefPtr& cancellable), g_resolver_lookup_by_name, errthrow) /** Synchronously resolves hostname to determine its associated IP address(es). * @a hostname may be an ASCII-only or UTF-8 hostname, or the textual form of an IP address (in which case this just becomes a wrapper around InetAddress:create_from_string()). * * On success, this will return a list of InetAddress, sorted in order of preference. (That is, you should attempt to connect to the first address first, then the second if the first fails, etc.) * * If the DNS resolution fails, a ResolverError exception will be thrown. * * If you are planning to connect to a socket on the resolved IP address, it may be easier to create a NetworkAddress and use its SocketConnectable base class. * * @param hostname hostname The hostname to look up. */ Glib::ListHandle< Glib::RefPtr > lookup_by_name(const Glib::ustring& hostname); /** Begins asynchronously resolving hostname to determine its associated IP address(es), and eventually calls @a slot, which must call * lookup_by_name_finish() to get the result. See lookup_by_name() for more details. * * @param hostname hostname The hostname to look up. * @param slot A callback slot to call after the resolution completes. * @param cancellable A Cancellable object which can be used to cancel the operation. */ void lookup_by_name_async(const Glib::ustring& hostname, const SlotAsyncReady& slot, const Glib::RefPtr& cancellable); /** Begins asynchronously resolving hostname to determine its associated IP address(es), and eventually calls @a slot, which must call * lookup_by_name_finish() to get the result. See lookup_by_name() for more details. * * @param hostname hostname The hostname to look up. * @param slot A callback slot to call after the resolution completes. */ void lookup_by_name_async(const Glib::ustring& hostname, const SlotAsyncReady& slot); _IGNORE(g_resolver_lookup_by_name_async) _WRAP_METHOD(Glib::ListHandle< Glib::RefPtr > lookup_by_name_finish(const Glib::RefPtr& result), g_resolver_lookup_by_name_finish, errthrow) _WRAP_METHOD(Glib::ustring lookup_by_address(const Glib::RefPtr& address, const Glib::RefPtr& cancellable), g_resolver_lookup_by_address, errthrow) /** Synchronously reverse-resolves an address to determine its associated hostname. * * If the DNS resolution fails then a ResolverError exception will be thrown. * * @param address The address to reverse-resolve. * @result A hostname (either ASCII-only, or in ASCII-encoded form), or an empty string on error. */ Glib::ustring lookup_by_address(const Glib::RefPtr& address); /** Begins asynchronously reverse-resolving an address to determine its associated hostname, and eventually calls callback, which must call * lookup_by_address_finish() to get the final result. * * @param address The address to reverse-resolve. * @param hostname hostname The hostname to look up. * @param slot A callback slot to call after the resolution completes. * @param cancellable A Cancellable object which can be used to cancel the operation. */ void lookup_by_address_async(const Glib::RefPtr& address, const SlotAsyncReady& slot, const Glib::RefPtr& cancellable); /** Begins asynchronously reverse-resolving an address to determine its associated hostname, and eventually calls callback, which must call * lookup_by_address_finish() to get the final result. * * @param address The address to reverse-resolve. * @param hostname hostname The hostname to look up. * @param slot A callback slot to call after the resolution completes. */ void lookup_by_address_async(const Glib::RefPtr& address, const SlotAsyncReady& slot); _IGNORE(g_resolver_lookup_by_address_async) _WRAP_METHOD(Glib::ustring lookup_by_address_finish(const Glib::RefPtr& result), g_resolver_lookup_by_address_finish, errthrow) #m4 _CONVERSION(`GList*',`ListHandle_SrvTarget',`$2($3, Glib::OWNERSHIP_DEEP)') _WRAP_METHOD(ListHandle_SrvTarget lookup_service(const Glib::ustring& service, const Glib::ustring& protocol, const Glib::ustring& domain, const Glib::RefPtr& cancellable), g_resolver_lookup_service, errthrow) /** Synchronously performs a DNS SRV lookup for the given service and protocol in the given domain and returns an list of SrvTargets. * @a domain may be an ASCII-only or UTF-8 hostname. Note also that the service and protocol arguments do not include the leading underscore that appears in the actual DNS entry. * * On success, this will return a list of SrvTargets, sorted in order of preference. * (That is, you should attempt to connect to the first target first, then the second if the first fails, etc.) * * If the DNS resolution fails a ResolverError exception will be thrown. * * If you are planning to connect to the service, it is usually easier to create a NetworkService and use its SocketConnectable base class interface. \ * * @param service The service type to look up (eg, "ldap"). * @param protocol The networking protocol to use for service (eg, "tcp") * @param domain The DNS domain to look up the service in. */ ListHandle_SrvTarget lookup_service(const Glib::ustring& service, const Glib::ustring& protocol, const Glib::ustring& domain); /** Begins asynchronously performing a DNS SRV lookup for the given service and protocol in the given domain, and eventually calls callback, * which must call lookup_service_finish() to get the final result. See glookup_service() for more details. * * @param service The service type to look up (eg, "ldap"). * @param protocol The networking protocol to use for service (eg, "tcp") * @param domain The DNS domain to look up the service in. * @param slot A callback slot to call after the resolution completes. * @param cancellable A Cancellable object which can be used to cancel the operation. */ void lookup_service_async(const Glib::ustring& service, const Glib::ustring& protocol, const Glib::ustring& domain, const SlotAsyncReady& slot, const Glib::RefPtr& cancellable); /** Begins asynchronously performing a DNS SRV lookup for the given service and protocol in the given domain, and eventually calls callback, * which must call lookup_service_finish() to get the final result. See glookup_service() for more details. * * @param service The service type to look up (eg, "ldap"). * @param protocol The networking protocol to use for service (eg, "tcp") * @param domain The DNS domain to look up the service in. * @param slot A callback slot to call after the resolution completes. */ void lookup_service_async(const Glib::ustring& service, const Glib::ustring& protocol, const Glib::ustring& domain, const SlotAsyncReady& slot); _IGNORE(g_resolver_lookup_service_async) _WRAP_METHOD(ListHandle_SrvTarget lookup_service_finish(const Glib::RefPtr& result), g_resolver_lookup_service_finish, errthrow) //TODO: Remove no_default_handler when we can break ABI: _WRAP_SIGNAL(void reload(), reload, no_default_handler) }; std::string hostname_to_ascii (const Glib::ustring& hostname); Glib::ustring hostname_to_unicode (const Glib::ustring& hostname); bool hostname_is_non_ascii (const Glib::ustring& hostname); bool hostname_is_ascii_encoded (const Glib::ustring& hostname); bool hostname_is_ip_address (const Glib::ustring& hostname); } // namespace Gio