1/* Copyright (C) 2009 jonathon jongsma
2 *
3 * This library is free software; you can redistribute it and/or
4 * modify it under the terms of the GNU Lesser General Public
5 * License as published by the Free Software Foundation; either
6 * version 2.1 of the License, or (at your option) any later version.
7 *
8 * This library is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
11 * Lesser General Public License for more details.
12 *
13 * You should have received a copy of the GNU Lesser General Public
14 * License along with this library.  If not, see <http://www.gnu.org/licenses/>.
15 */
16
17#include <glibmm/object.h>
18#include <giomm/inetaddress.h>
19#include <giomm/cancellable.h>
20#include <giomm/srvtarget.h>
21#include <giomm/asyncresult.h>
22
23_DEFS(giomm,gio)
24_PINCLUDE(glibmm/private/object_p.h)
25
26
27// Forward declarations for classes in the Glib namespace.
28namespace Glib
29{
30
31class GLIBMM_API VariantContainerBase;
32
33}
34
35namespace Gio
36{
37
38_WRAP_ENUM(ResolverRecordType, GResolverRecordType)
39
40/** Asynchronous and cancellable DNS resolver
41 *
42 * Resolver provides cancellable synchronous and asynchronous DNS resolution,
43 * for hostnames (lookup_by_address(), lookup_by_name() and their async
44 * variants) and SRV (service) records (lookup_service()).
45 *
46 * NetworkAddress and NetworkService provide wrappers around Resolver
47 * functionality that also implement SocketConnectable, making it easy to
48 * connect to a remote host/service.
49 *
50 * @newin{2,24}
51 * @ingroup NetworkIO
52 */
53class GIOMM_API Resolver
54: public Glib::Object
55{
56  _CLASS_GOBJECT(Resolver, GResolver, G_RESOLVER, Glib::Object, GObject, , , GIOMM_API)
57
58protected:
59
60public:
61  static Glib::RefPtr<Resolver> get_default();
62  _IGNORE(g_resolver_get_default)
63  static void set_default(const Glib::RefPtr<Resolver>& resolver);
64  _IGNORE(g_resolver_set_default)
65
66  // g_resolver_free_addresses is just a C convenience function
67  _IGNORE(g_resolver_free_addresses)
68
69#m4 _CONVERSION(`GList*',`Glib::ListHandle< Glib::RefPtr<InetAddress> >',`$2($3, Glib::OWNERSHIP_DEEP)')
70  _WRAP_METHOD(Glib::ListHandle< Glib::RefPtr<InetAddress> > lookup_by_name(const Glib::ustring& hostname, const Glib::RefPtr<Cancellable>& cancellable{?}), g_resolver_lookup_by_name, errthrow)
71
72  /** Begins asynchronously resolving hostname to determine its associated IP address(es), and eventually calls @a slot, which must call
73   * lookup_by_name_finish() to get the result. See lookup_by_name() for more details.
74   *
75   * @param hostname The hostname to look up.
76   * @param slot A callback slot to call after the resolution completes.
77   * @param cancellable A Cancellable object which can be used to cancel the operation.
78   */
79  void lookup_by_name_async(const Glib::ustring& hostname, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable);
80
81  /** Begins asynchronously resolving hostname to determine its associated IP address(es), and eventually calls @a slot, which must call
82   * lookup_by_name_finish() to get the result. See lookup_by_name() for more details.
83   *
84   * @param hostname The hostname to look up.
85   * @param slot A callback slot to call after the resolution completes.
86   */
87  void lookup_by_name_async(const Glib::ustring& hostname, const SlotAsyncReady& slot);
88  _IGNORE(g_resolver_lookup_by_name_async)
89
90  _WRAP_METHOD(Glib::ListHandle< Glib::RefPtr<InetAddress> > lookup_by_name_finish(const Glib::RefPtr<AsyncResult>& result), g_resolver_lookup_by_name_finish, errthrow)
91
92  _WRAP_METHOD(Glib::ustring lookup_by_address(const Glib::RefPtr<InetAddress>& address, const Glib::RefPtr<Cancellable>& cancellable{?}), g_resolver_lookup_by_address, errthrow)
93
94  /** Begins asynchronously reverse-resolving an address to determine its associated hostname, and eventually calls callback, which must call
95   * lookup_by_address_finish() to get the final result.
96   *
97   * @param address The address to reverse-resolve.
98   * @param slot A callback slot to call after the resolution completes.
99   * @param cancellable A Cancellable object which can be used to cancel the operation.
100   */
101  void lookup_by_address_async(const Glib::RefPtr<InetAddress>& address, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable);
102
103  /** Begins asynchronously reverse-resolving an address to determine its associated hostname, and eventually calls callback, which must call
104   * lookup_by_address_finish() to get the final result.
105   *
106   * @param address The address to reverse-resolve.
107   * @param slot A callback slot to call after the resolution completes.
108   */
109  void lookup_by_address_async(const Glib::RefPtr<InetAddress>& address, const SlotAsyncReady& slot);
110  _IGNORE(g_resolver_lookup_by_address_async)
111
112  _WRAP_METHOD(Glib::ustring lookup_by_address_finish(const Glib::RefPtr<AsyncResult>& result), g_resolver_lookup_by_address_finish, errthrow)
113
114#m4 _CONVERSION(`GList*',`ListHandle_SrvTarget',`$2($3, Glib::OWNERSHIP_DEEP)')
115  _WRAP_METHOD(ListHandle_SrvTarget lookup_service(const Glib::ustring& service, const Glib::ustring& protocol, const Glib::ustring& domain, const Glib::RefPtr<Cancellable>& cancellable{?}), g_resolver_lookup_service, errthrow)
116
117  /** Begins asynchronously performing a DNS SRV lookup for the given service and protocol in the given domain, and eventually calls callback,
118   * which must call lookup_service_finish() to get the final result. See glookup_service() for more details.
119   *
120   * @param service The service type to look up (eg, "ldap").
121   * @param protocol The networking protocol to use for service (eg, "tcp")
122   * @param domain The DNS domain to look up the service in.
123   * @param slot A callback slot to call after the resolution completes.
124   * @param cancellable A Cancellable object which can be used to cancel the operation.
125   */
126  void lookup_service_async(const Glib::ustring& service, const Glib::ustring& protocol, const Glib::ustring& domain, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable);
127
128  /** Begins asynchronously performing a DNS SRV lookup for the given service and protocol in the given domain, and eventually calls callback,
129   * which must call lookup_service_finish() to get the final result. See glookup_service() for more details.
130   *
131   * @param service The service type to look up (eg, "ldap").
132   * @param protocol The networking protocol to use for service (eg, "tcp")
133   * @param domain The DNS domain to look up the service in.
134   * @param slot A callback slot to call after the resolution completes.
135   */
136  void lookup_service_async(const Glib::ustring& service, const Glib::ustring& protocol, const Glib::ustring& domain, const SlotAsyncReady& slot);
137  _IGNORE(g_resolver_lookup_service_async)
138
139  _WRAP_METHOD(ListHandle_SrvTarget lookup_service_finish(const Glib::RefPtr<AsyncResult>& result), g_resolver_lookup_service_finish, errthrow)
140
141#m4 _CONVERSION(`GList*',`std::vector<Glib::VariantContainerBase>',`Glib::ListHandler<Glib::VariantContainerBase>::list_to_vector($3, Glib::OWNERSHIP_DEEP)')
142
143  _WRAP_METHOD(std::vector<Glib::VariantContainerBase> lookup_records(const Glib::ustring& rrname, ResolverRecordType record_type, const Glib::RefPtr<Cancellable>& cancellable{?}), g_resolver_lookup_records, errthrow)
144
145  /** Begins asynchronously performing a DNS lookup for the given @a rrname,
146   * and eventually calls @a slot, which must call lookup_records_finish() to
147   * get the final result. See lookup_records() for more details.
148   *
149   * @param rrname The DNS name to lookup the record for.
150   * @param record_type The type of DNS record to lookup.
151   * @param cancellable A Cancellable.
152   * @param slot The slot to call after the resolution completes.
153   * @newin{2,36}
154   */
155  void lookup_records_async(const Glib::ustring& rrname,
156    ResolverRecordType record_type, const SlotAsyncReady& slot,
157    const Glib::RefPtr<Cancellable>& cancellable);
158  _IGNORE(g_resolver_lookup_records_async)
159
160  /// A non-cancellable version of lookup_records_async().
161  void lookup_records_async(const Glib::ustring& rrname,
162    ResolverRecordType record_type, const SlotAsyncReady& slot);
163
164  _WRAP_METHOD(std::vector<Glib::VariantContainerBase> lookup_records_finish(const Glib::RefPtr<AsyncResult>& result), g_resolver_lookup_records_finish, errthrow)
165
166  //TODO: Remove no_default_handler when we can break ABI:
167  _WRAP_SIGNAL(void reload(), reload, no_default_handler)
168};
169
170GIOMM_API
171std::string hostname_to_ascii (const Glib::ustring& hostname);
172
173GIOMM_API
174Glib::ustring hostname_to_unicode (const Glib::ustring& hostname);
175
176GIOMM_API
177bool hostname_is_non_ascii (const Glib::ustring& hostname);
178
179GIOMM_API
180bool hostname_is_ascii_encoded (const Glib::ustring& hostname);
181
182GIOMM_API
183bool hostname_is_ip_address (const Glib::ustring& hostname);
184
185} // namespace Gio
186