1 // Generated by gmmproc 2.64.2 -- DO NOT MODIFY! 2 #ifndef _GIOMM_RESOLVER_H 3 #define _GIOMM_RESOLVER_H 4 5 6 #include <glibmm/ustring.h> 7 #include <sigc++/sigc++.h> 8 9 /* Copyright (C) 2009 jonathon jongsma 10 * 11 * This library is free software; you can redistribute it and/or 12 * modify it under the terms of the GNU Lesser General Public 13 * License as published by the Free Software Foundation; either 14 * version 2.1 of the License, or (at your option) any later version. 15 * 16 * This library is distributed in the hope that it will be useful, 17 * but WITHOUT ANY WARRANTY; without even the implied warranty of 18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 19 * Lesser General Public License for more details. 20 * 21 * You should have received a copy of the GNU Lesser General Public 22 * License along with this library. If not, see <http://www.gnu.org/licenses/>. 23 */ 24 25 #include <glibmm/object.h> 26 #include <giomm/inetaddress.h> 27 #include <giomm/cancellable.h> 28 #include <giomm/srvtarget.h> 29 #include <giomm/asyncresult.h> 30 31 32 // Forward declarations for classes in the Glib namespace. 33 #ifndef DOXYGEN_SHOULD_SKIP_THIS 34 using GResolver = struct _GResolver; 35 using GResolverClass = struct _GResolverClass; 36 #endif /* DOXYGEN_SHOULD_SKIP_THIS */ 37 38 39 #ifndef DOXYGEN_SHOULD_SKIP_THIS 40 namespace Gio 41 { class GIOMM_API Resolver_Class; } // namespace Gio 42 #endif //DOXYGEN_SHOULD_SKIP_THIS 43 44 namespace Glib 45 { 46 47 class GLIBMM_API VariantContainerBase; 48 49 } 50 51 namespace Gio 52 { 53 54 /** @addtogroup giommEnums giomm Enums and Flags */ 55 56 /** 57 * @var ResolverRecordType RESOLVER_RECORD_SRV 58 * Look up DNS SRV records for a domain. 59 * 60 * @var ResolverRecordType RESOLVER_RECORD_MX 61 * Look up DNS MX records for a domain. 62 * 63 * @var ResolverRecordType RESOLVER_RECORD_TXT 64 * Look up DNS TXT records for a name. 65 * 66 * @var ResolverRecordType RESOLVER_RECORD_SOA 67 * Look up DNS SOA records for a zone. 68 * 69 * @var ResolverRecordType RESOLVER_RECORD_NS 70 * Look up DNS NS records for a domain. 71 * 72 * @enum ResolverRecordType 73 * 74 * The type of record that g_resolver_lookup_records() or 75 * g_resolver_lookup_records_async() should retrieve. The records are returned 76 * as lists of Variant tuples. Each record type has different values in 77 * the variant tuples returned. 78 * 79 * RESOLVER_RECORD_SRV records are returned as variants with the signature 80 * `(qqqs)`, containing a `guint16` with the priority, a `guint16` with the 81 * weight, a `guint16` with the port, and a string of the hostname. 82 * 83 * RESOLVER_RECORD_MX records are returned as variants with the signature 84 * `(qs)`, representing a `guint16` with the preference, and a string containing 85 * the mail exchanger hostname. 86 * 87 * RESOLVER_RECORD_TXT records are returned as variants with the signature 88 * `(as)`, representing an array of the strings in the text record. Note: Most TXT 89 * records only contain a single string, but 90 * [RFC 1035](https://tools.ietf.org/html/rfc1035#section-3.3.14) does allow a 91 * record to contain multiple strings. The RFC which defines the interpretation 92 * of a specific TXT record will likely require concatenation of multiple 93 * strings if they are present, as with 94 * [RFC 7208](https://tools.ietf.org/html/rfc7208#section-3.3). 95 * 96 * RESOLVER_RECORD_SOA records are returned as variants with the signature 97 * `(ssuuuuu)`, representing a string containing the primary name server, a 98 * string containing the administrator, the serial as a `guint32`, the refresh 99 * interval as a `guint32`, the retry interval as a `guint32`, the expire timeout 100 * as a `guint32`, and the TTL as a `guint32`. 101 * 102 * RESOLVER_RECORD_NS records are returned as variants with the signature 103 * `(s)`, representing a string of the hostname of the name server. 104 * 105 * @newin{2,34} 106 * 107 * @ingroup giommEnums 108 */ 109 enum ResolverRecordType 110 { 111 RESOLVER_RECORD_SRV = 1, 112 RESOLVER_RECORD_MX, 113 RESOLVER_RECORD_TXT, 114 RESOLVER_RECORD_SOA, 115 RESOLVER_RECORD_NS 116 }; 117 118 } // namespace Gio 119 120 #ifndef DOXYGEN_SHOULD_SKIP_THIS 121 namespace Glib 122 { 123 124 template <> 125 class Value<Gio::ResolverRecordType> : public Glib::Value_Enum<Gio::ResolverRecordType> 126 { 127 public: 128 static GType value_type() G_GNUC_CONST; 129 }; 130 131 } // namespace Glib 132 #endif /* DOXYGEN_SHOULD_SKIP_THIS */ 133 134 namespace Gio 135 { 136 137 138 /** Asynchronous and cancellable DNS resolver 139 * 140 * Resolver provides cancellable synchronous and asynchronous DNS resolution, 141 * for hostnames (lookup_by_address(), lookup_by_name() and their async 142 * variants) and SRV (service) records (lookup_service()). 143 * 144 * NetworkAddress and NetworkService provide wrappers around Resolver 145 * functionality that also implement SocketConnectable, making it easy to 146 * connect to a remote host/service. 147 * 148 * @newin{2,24} 149 * @ingroup NetworkIO 150 */ 151 152 class GIOMM_API Resolver 153 : public Glib::Object 154 { 155 156 #ifndef DOXYGEN_SHOULD_SKIP_THIS 157 158 public: 159 using CppObjectType = Resolver; 160 using CppClassType = Resolver_Class; 161 using BaseObjectType = GResolver; 162 using BaseClassType = GResolverClass; 163 164 // noncopyable 165 Resolver(const Resolver&) = delete; 166 Resolver& operator=(const Resolver&) = delete; 167 168 private: friend class Resolver_Class; 169 static CppClassType resolver_class_; 170 171 protected: 172 explicit Resolver(const Glib::ConstructParams& construct_params); 173 explicit Resolver(GResolver* castitem); 174 175 #endif /* DOXYGEN_SHOULD_SKIP_THIS */ 176 177 public: 178 179 Resolver(Resolver&& src) noexcept; 180 Resolver& operator=(Resolver&& src) noexcept; 181 182 ~Resolver() noexcept override; 183 184 /** Get the GType for this class, for use with the underlying GObject type system. 185 */ 186 static GType get_type() G_GNUC_CONST; 187 188 #ifndef DOXYGEN_SHOULD_SKIP_THIS 189 190 191 static GType get_base_type() G_GNUC_CONST; 192 #endif 193 194 ///Provides access to the underlying C GObject. gobj()195 GResolver* gobj() { return reinterpret_cast<GResolver*>(gobject_); } 196 197 ///Provides access to the underlying C GObject. gobj()198 const GResolver* gobj() const { return reinterpret_cast<GResolver*>(gobject_); } 199 200 ///Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs. 201 GResolver* gobj_copy(); 202 203 private: 204 205 206 protected: 207 208 public: 209 static Glib::RefPtr<Resolver> get_default(); 210 211 static void set_default(const Glib::RefPtr<Resolver>& resolver); 212 213 214 // g_resolver_free_addresses is just a C convenience function 215 216 217 /** Synchronously resolves @a hostname to determine its associated IP 218 * address(es). @a hostname may be an ASCII-only or UTF-8 hostname, or 219 * the textual form of an IP address (in which case this just becomes 220 * a wrapper around g_inet_address_new_from_string()). 221 * 222 * On success, g_resolver_lookup_by_name() will return a non-empty List of 223 * InetAddress, sorted in order of preference and guaranteed to not 224 * contain duplicates. That is, if using the result to connect to 225 * @a hostname, you should attempt to connect to the first address 226 * first, then the second if the first fails, etc. If you are using 227 * the result to listen on a socket, it is appropriate to add each 228 * result using e.g. g_socket_listener_add_address(). 229 * 230 * If the DNS resolution fails, @a error (if non-<tt>nullptr</tt>) will be set to a 231 * value from ResolverError and <tt>nullptr</tt> will be returned. 232 * 233 * If @a cancellable is non-<tt>nullptr</tt>, it can be used to cancel the 234 * operation, in which case @a error (if non-<tt>nullptr</tt>) will be set to 235 * IO_ERROR_CANCELLED. 236 * 237 * If you are planning to connect to a socket on the resolved IP 238 * address, it may be easier to create a NetworkAddress and use its 239 * SocketConnectable interface. 240 * 241 * @newin{2,22} 242 * 243 * @param hostname The hostname to look up. 244 * @param cancellable A Cancellable, or <tt>nullptr</tt>. 245 * @return A non-empty List 246 * of InetAddress, or <tt>nullptr</tt> on error. You 247 * must unref each of the addresses and free the list when you are 248 * done with it. (You can use g_resolver_free_addresses() to do this.). 249 * 250 * @throws Glib::Error 251 */ 252 Glib::ListHandle< Glib::RefPtr<InetAddress> > lookup_by_name(const Glib::ustring& hostname, const Glib::RefPtr<Cancellable>& cancellable); 253 254 /// A lookup_by_name() convenience overload. 255 Glib::ListHandle< Glib::RefPtr<InetAddress> > lookup_by_name(const Glib::ustring& hostname); 256 257 /** Begins asynchronously resolving hostname to determine its associated IP address(es), and eventually calls @a slot, which must call 258 * lookup_by_name_finish() to get the result. See lookup_by_name() for more details. 259 * 260 * @param hostname The hostname to look up. 261 * @param slot A callback slot to call after the resolution completes. 262 * @param cancellable A Cancellable object which can be used to cancel the operation. 263 */ 264 void lookup_by_name_async(const Glib::ustring& hostname, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable); 265 266 /** Begins asynchronously resolving hostname to determine its associated IP address(es), and eventually calls @a slot, which must call 267 * lookup_by_name_finish() to get the result. See lookup_by_name() for more details. 268 * 269 * @param hostname The hostname to look up. 270 * @param slot A callback slot to call after the resolution completes. 271 */ 272 void lookup_by_name_async(const Glib::ustring& hostname, const SlotAsyncReady& slot); 273 274 275 /** Retrieves the result of a call to 276 * g_resolver_lookup_by_name_async(). 277 * 278 * If the DNS resolution failed, @a error (if non-<tt>nullptr</tt>) will be set to 279 * a value from ResolverError. If the operation was cancelled, 280 * @a error will be set to IO_ERROR_CANCELLED. 281 * 282 * @newin{2,22} 283 * 284 * @param result The result passed to your SlotAsyncReady. 285 * @return A List 286 * of InetAddress, or <tt>nullptr</tt> on error. See g_resolver_lookup_by_name() 287 * for more details. 288 * 289 * @throws Glib::Error 290 */ 291 Glib::ListHandle< Glib::RefPtr<InetAddress> > lookup_by_name_finish(const Glib::RefPtr<AsyncResult>& result); 292 293 294 /** Synchronously reverse-resolves @a address to determine its 295 * associated hostname. 296 * 297 * If the DNS resolution fails, @a error (if non-<tt>nullptr</tt>) will be set to 298 * a value from ResolverError. 299 * 300 * If @a cancellable is non-<tt>nullptr</tt>, it can be used to cancel the 301 * operation, in which case @a error (if non-<tt>nullptr</tt>) will be set to 302 * IO_ERROR_CANCELLED. 303 * 304 * @newin{2,22} 305 * 306 * @param address The address to reverse-resolve. 307 * @param cancellable A Cancellable, or <tt>nullptr</tt>. 308 * @return A hostname (either ASCII-only, or in ASCII-encoded 309 * form), or <tt>nullptr</tt> on error. 310 * 311 * @throws Glib::Error 312 */ 313 Glib::ustring lookup_by_address(const Glib::RefPtr<InetAddress>& address, const Glib::RefPtr<Cancellable>& cancellable); 314 315 /// A lookup_by_address() convenience overload. 316 Glib::ustring lookup_by_address(const Glib::RefPtr<InetAddress>& address); 317 318 /** Begins asynchronously reverse-resolving an address to determine its associated hostname, and eventually calls callback, which must call 319 * lookup_by_address_finish() to get the final result. 320 * 321 * @param address The address to reverse-resolve. 322 * @param slot A callback slot to call after the resolution completes. 323 * @param cancellable A Cancellable object which can be used to cancel the operation. 324 */ 325 void lookup_by_address_async(const Glib::RefPtr<InetAddress>& address, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable); 326 327 /** Begins asynchronously reverse-resolving an address to determine its associated hostname, and eventually calls callback, which must call 328 * lookup_by_address_finish() to get the final result. 329 * 330 * @param address The address to reverse-resolve. 331 * @param slot A callback slot to call after the resolution completes. 332 */ 333 void lookup_by_address_async(const Glib::RefPtr<InetAddress>& address, const SlotAsyncReady& slot); 334 335 336 /** Retrieves the result of a previous call to 337 * g_resolver_lookup_by_address_async(). 338 * 339 * If the DNS resolution failed, @a error (if non-<tt>nullptr</tt>) will be set to 340 * a value from ResolverError. If the operation was cancelled, 341 * @a error will be set to IO_ERROR_CANCELLED. 342 * 343 * @newin{2,22} 344 * 345 * @param result The result passed to your SlotAsyncReady. 346 * @return A hostname (either ASCII-only, or in ASCII-encoded 347 * form), or <tt>nullptr</tt> on error. 348 * 349 * @throws Glib::Error 350 */ 351 Glib::ustring lookup_by_address_finish(const Glib::RefPtr<AsyncResult>& result); 352 353 354 /** Synchronously performs a DNS SRV lookup for the given @a service and 355 * @a protocol in the given @a domain and returns an array of SrvTarget. 356 * @a domain may be an ASCII-only or UTF-8 hostname. Note also that the 357 * @a service and @a protocol arguments do not include the leading underscore 358 * that appears in the actual DNS entry. 359 * 360 * On success, g_resolver_lookup_service() will return a non-empty List of 361 * SrvTarget, sorted in order of preference. (That is, you should 362 * attempt to connect to the first target first, then the second if 363 * the first fails, etc.) 364 * 365 * If the DNS resolution fails, @a error (if non-<tt>nullptr</tt>) will be set to 366 * a value from ResolverError and <tt>nullptr</tt> will be returned. 367 * 368 * If @a cancellable is non-<tt>nullptr</tt>, it can be used to cancel the 369 * operation, in which case @a error (if non-<tt>nullptr</tt>) will be set to 370 * IO_ERROR_CANCELLED. 371 * 372 * If you are planning to connect to the service, it is usually easier 373 * to create a NetworkService and use its SocketConnectable 374 * interface. 375 * 376 * @newin{2,22} 377 * 378 * @param service The service type to look up (eg, "ldap"). 379 * @param protocol The networking protocol to use for @a service (eg, "tcp"). 380 * @param domain The DNS domain to look up the service in. 381 * @param cancellable A Cancellable, or <tt>nullptr</tt>. 382 * @return A non-empty List of 383 * SrvTarget, or <tt>nullptr</tt> on error. You must free each of the targets and the 384 * list when you are done with it. (You can use g_resolver_free_targets() to do 385 * this.). 386 * 387 * @throws Glib::Error 388 */ 389 ListHandle_SrvTarget lookup_service(const Glib::ustring& service, const Glib::ustring& protocol, const Glib::ustring& domain, const Glib::RefPtr<Cancellable>& cancellable); 390 391 /// A lookup_service() convenience overload. 392 ListHandle_SrvTarget lookup_service(const Glib::ustring& service, const Glib::ustring& protocol, const Glib::ustring& domain); 393 394 /** Begins asynchronously performing a DNS SRV lookup for the given service and protocol in the given domain, and eventually calls callback, 395 * which must call lookup_service_finish() to get the final result. See glookup_service() for more details. 396 * 397 * @param service The service type to look up (eg, "ldap"). 398 * @param protocol The networking protocol to use for service (eg, "tcp") 399 * @param domain The DNS domain to look up the service in. 400 * @param slot A callback slot to call after the resolution completes. 401 * @param cancellable A Cancellable object which can be used to cancel the operation. 402 */ 403 void lookup_service_async(const Glib::ustring& service, const Glib::ustring& protocol, const Glib::ustring& domain, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable); 404 405 /** Begins asynchronously performing a DNS SRV lookup for the given service and protocol in the given domain, and eventually calls callback, 406 * which must call lookup_service_finish() to get the final result. See glookup_service() for more details. 407 * 408 * @param service The service type to look up (eg, "ldap"). 409 * @param protocol The networking protocol to use for service (eg, "tcp") 410 * @param domain The DNS domain to look up the service in. 411 * @param slot A callback slot to call after the resolution completes. 412 */ 413 void lookup_service_async(const Glib::ustring& service, const Glib::ustring& protocol, const Glib::ustring& domain, const SlotAsyncReady& slot); 414 415 416 /** Retrieves the result of a previous call to 417 * g_resolver_lookup_service_async(). 418 * 419 * If the DNS resolution failed, @a error (if non-<tt>nullptr</tt>) will be set to 420 * a value from ResolverError. If the operation was cancelled, 421 * @a error will be set to IO_ERROR_CANCELLED. 422 * 423 * @newin{2,22} 424 * 425 * @param result The result passed to your SlotAsyncReady. 426 * @return A non-empty List of 427 * SrvTarget, or <tt>nullptr</tt> on error. See g_resolver_lookup_service() for more 428 * details. 429 * 430 * @throws Glib::Error 431 */ 432 ListHandle_SrvTarget lookup_service_finish(const Glib::RefPtr<AsyncResult>& result); 433 434 435 /** Synchronously performs a DNS record lookup for the given @a rrname and returns 436 * a list of records as Variant tuples. See ResolverRecordType for 437 * information on what the records contain for each @a record_type. 438 * 439 * If the DNS resolution fails, @a error (if non-<tt>nullptr</tt>) will be set to 440 * a value from ResolverError and <tt>nullptr</tt> will be returned. 441 * 442 * If @a cancellable is non-<tt>nullptr</tt>, it can be used to cancel the 443 * operation, in which case @a error (if non-<tt>nullptr</tt>) will be set to 444 * IO_ERROR_CANCELLED. 445 * 446 * @newin{2,34} 447 * 448 * @param rrname The DNS name to look up the record for. 449 * @param record_type The type of DNS record to look up. 450 * @param cancellable A Cancellable, or <tt>nullptr</tt>. 451 * @return A non-empty List of 452 * Variant, or <tt>nullptr</tt> on error. You must free each of the records and the list 453 * when you are done with it. (You can use Glib::list_free_full() with 454 * Glib::variant_unref() to do this.). 455 * 456 * @throws Glib::Error 457 */ 458 std::vector<Glib::VariantContainerBase> lookup_records(const Glib::ustring& rrname, ResolverRecordType record_type, const Glib::RefPtr<Cancellable>& cancellable); 459 460 /// A lookup_records() convenience overload. 461 std::vector<Glib::VariantContainerBase> lookup_records(const Glib::ustring& rrname, ResolverRecordType record_type); 462 463 /** Begins asynchronously performing a DNS lookup for the given @a rrname, 464 * and eventually calls @a slot, which must call lookup_records_finish() to 465 * get the final result. See lookup_records() for more details. 466 * 467 * @param rrname The DNS name to lookup the record for. 468 * @param record_type The type of DNS record to lookup. 469 * @param cancellable A Cancellable. 470 * @param slot The slot to call after the resolution completes. 471 * @newin{2,36} 472 */ 473 void lookup_records_async(const Glib::ustring& rrname, 474 ResolverRecordType record_type, const SlotAsyncReady& slot, 475 const Glib::RefPtr<Cancellable>& cancellable); 476 477 478 /// A non-cancellable version of lookup_records_async(). 479 void lookup_records_async(const Glib::ustring& rrname, 480 ResolverRecordType record_type, const SlotAsyncReady& slot); 481 482 483 /** Retrieves the result of a previous call to 484 * g_resolver_lookup_records_async(). Returns a non-empty list of records as 485 * Variant tuples. See ResolverRecordType for information on what the 486 * records contain. 487 * 488 * If the DNS resolution failed, @a error (if non-<tt>nullptr</tt>) will be set to 489 * a value from ResolverError. If the operation was cancelled, 490 * @a error will be set to IO_ERROR_CANCELLED. 491 * 492 * @newin{2,34} 493 * 494 * @param result The result passed to your SlotAsyncReady. 495 * @return A non-empty List of 496 * Variant, or <tt>nullptr</tt> on error. You must free each of the records and the list 497 * when you are done with it. (You can use Glib::list_free_full() with 498 * Glib::variant_unref() to do this.). 499 * 500 * @throws Glib::Error 501 */ 502 std::vector<Glib::VariantContainerBase> lookup_records_finish(const Glib::RefPtr<AsyncResult>& result); 503 504 //TODO: Remove no_default_handler when we can break ABI: 505 506 /** 507 * @par Slot Prototype: 508 * <tt>void on_my_%reload()</tt> 509 * 510 * Flags: Run Last 511 * 512 * Emitted when the resolver notices that the system resolver 513 * configuration has changed. 514 */ 515 516 Glib::SignalProxy< void > signal_reload(); 517 518 519 public: 520 521 public: 522 //C++ methods used to invoke GTK+ virtual functions: 523 524 protected: 525 //GTK+ Virtual Functions (override these to change behaviour): 526 527 //Default Signal Handlers:: 528 529 530 }; 531 532 GIOMM_API 533 std::string hostname_to_ascii (const Glib::ustring& hostname); 534 535 GIOMM_API 536 Glib::ustring hostname_to_unicode (const Glib::ustring& hostname); 537 538 GIOMM_API 539 bool hostname_is_non_ascii (const Glib::ustring& hostname); 540 541 GIOMM_API 542 bool hostname_is_ascii_encoded (const Glib::ustring& hostname); 543 544 GIOMM_API 545 bool hostname_is_ip_address (const Glib::ustring& hostname); 546 547 } // namespace Gio 548 549 550 namespace Glib 551 { 552 /** A Glib::wrap() method for this object. 553 * 554 * @param object The C instance. 555 * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref. 556 * @result A C++ instance that wraps this C instance. 557 * 558 * @relates Gio::Resolver 559 */ 560 GIOMM_API 561 Glib::RefPtr<Gio::Resolver> wrap(GResolver* object, bool take_copy = false); 562 } 563 564 565 #endif /* _GIOMM_RESOLVER_H */ 566 567