source: appstream-generator/build/girepo/gio/Resolver.d @ 4841

Last change on this file since 4841 was 4841, checked in by Juanma, 2 years ago

Initial release

File size: 19.1 KB
Line 
1/*
2 * Licensed under the GNU Lesser General Public License Version 3
3 *
4 * This library is free software: you can redistribute it and/or modify
5 * it under the terms of the GNU Lesser General Public License as published by
6 * the Free Software Foundation, either version 3 of the license, or
7 * (at your option) any later version.
8 *
9 * This software is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 * GNU Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public License
15 * along with this library.  If not, see <http://www.gnu.org/licenses/>.
16 */
17
18// generated automatically - do not change
19
20
21module gio.Resolver;
22
23private import gi.gio;
24public  import gi.giotypes;
25private import gio.AsyncResultIF;
26private import gio.Cancellable;
27private import gio.InetAddress;
28private import glib.ErrorG;
29private import glib.GException;
30private import glib.ListG;
31private import glib.Str;
32private import gobject.ObjectG;
33private import gobject.Signals;
34private import std.algorithm;
35
36
37/**
38 * #GResolver provides cancellable synchronous and asynchronous DNS
39 * resolution, for hostnames (g_resolver_lookup_by_address(),
40 * g_resolver_lookup_by_name() and their async variants) and SRV
41 * (service) records (g_resolver_lookup_service()).
42 *
43 * #GNetworkAddress and #GNetworkService provide wrappers around
44 * #GResolver functionality that also implement #GSocketConnectable,
45 * making it easy to connect to a remote host/service.
46 */
47public class Resolver : ObjectG
48{
49        /** the main Gtk struct */
50        protected GResolver* gResolver;
51
52        /** Get the main Gtk struct */
53        public GResolver* getResolverStruct()
54        {
55                return gResolver;
56        }
57
58        /** the main Gtk struct as a void* */
59        protected override void* getStruct()
60        {
61                return cast(void*)gResolver;
62        }
63
64        protected override void setStruct(GObject* obj)
65        {
66                gResolver = cast(GResolver*)obj;
67                super.setStruct(obj);
68        }
69
70        /**
71         * Sets our main struct and passes it to the parent class.
72         */
73        public this (GResolver* gResolver, bool ownedRef = false)
74        {
75                this.gResolver = gResolver;
76                super(cast(GObject*)gResolver, ownedRef);
77        }
78
79
80        /** */
81        public static GType getType()
82        {
83                return g_resolver_get_type();
84        }
85
86        /**
87         * Frees @addresses (which should be the return value from
88         * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_finish()).
89         * (This is a convenience method; you can also simply free the results
90         * by hand.)
91         *
92         * Params:
93         *     addresses = a #GList of #GInetAddress
94         *
95         * Since: 2.22
96         */
97        public static void freeAddresses(ListG addresses)
98        {
99                g_resolver_free_addresses((addresses is null) ? null : addresses.getListGStruct());
100        }
101
102        /**
103         * Frees @targets (which should be the return value from
104         * g_resolver_lookup_service() or g_resolver_lookup_service_finish()).
105         * (This is a convenience method; you can also simply free the
106         * results by hand.)
107         *
108         * Params:
109         *     targets = a #GList of #GSrvTarget
110         *
111         * Since: 2.22
112         */
113        public static void freeTargets(ListG targets)
114        {
115                g_resolver_free_targets((targets is null) ? null : targets.getListGStruct());
116        }
117
118        /**
119         * Gets the default #GResolver. You should unref it when you are done
120         * with it. #GResolver may use its reference count as a hint about how
121         * many threads it should allocate for concurrent DNS resolutions.
122         *
123         * Returns: the default #GResolver.
124         *
125         * Since: 2.22
126         */
127        public static Resolver getDefault()
128        {
129                auto p = g_resolver_get_default();
130               
131                if(p is null)
132                {
133                        return null;
134                }
135               
136                return ObjectG.getDObject!(Resolver)(cast(GResolver*) p, true);
137        }
138
139        /**
140         * Synchronously reverse-resolves @address to determine its
141         * associated hostname.
142         *
143         * If the DNS resolution fails, @error (if non-%NULL) will be set to
144         * a value from #GResolverError.
145         *
146         * If @cancellable is non-%NULL, it can be used to cancel the
147         * operation, in which case @error (if non-%NULL) will be set to
148         * %G_IO_ERROR_CANCELLED.
149         *
150         * Params:
151         *     address = the address to reverse-resolve
152         *     cancellable = a #GCancellable, or %NULL
153         *
154         * Returns: a hostname (either ASCII-only, or in ASCII-encoded
155         *     form), or %NULL on error.
156         *
157         * Since: 2.22
158         *
159         * Throws: GException on failure.
160         */
161        public string lookupByAddress(InetAddress address, Cancellable cancellable)
162        {
163                GError* err = null;
164               
165                auto retStr = g_resolver_lookup_by_address(gResolver, (address is null) ? null : address.getInetAddressStruct(), (cancellable is null) ? null : cancellable.getCancellableStruct(), &err);
166               
167                if (err !is null)
168                {
169                        throw new GException( new ErrorG(err) );
170                }
171               
172                scope(exit) Str.freeString(retStr);
173                return Str.toString(retStr);
174        }
175
176        /**
177         * Begins asynchronously reverse-resolving @address to determine its
178         * associated hostname, and eventually calls @callback, which must
179         * call g_resolver_lookup_by_address_finish() to get the final result.
180         *
181         * Params:
182         *     address = the address to reverse-resolve
183         *     cancellable = a #GCancellable, or %NULL
184         *     callback = callback to call after resolution completes
185         *     userData = data for @callback
186         *
187         * Since: 2.22
188         */
189        public void lookupByAddressAsync(InetAddress address, Cancellable cancellable, GAsyncReadyCallback callback, void* userData)
190        {
191                g_resolver_lookup_by_address_async(gResolver, (address is null) ? null : address.getInetAddressStruct(), (cancellable is null) ? null : cancellable.getCancellableStruct(), callback, userData);
192        }
193
194        /**
195         * Retrieves the result of a previous call to
196         * g_resolver_lookup_by_address_async().
197         *
198         * If the DNS resolution failed, @error (if non-%NULL) will be set to
199         * a value from #GResolverError. If the operation was cancelled,
200         * @error will be set to %G_IO_ERROR_CANCELLED.
201         *
202         * Params:
203         *     result = the result passed to your #GAsyncReadyCallback
204         *
205         * Returns: a hostname (either ASCII-only, or in ASCII-encoded
206         *     form), or %NULL on error.
207         *
208         * Since: 2.22
209         *
210         * Throws: GException on failure.
211         */
212        public string lookupByAddressFinish(AsyncResultIF result)
213        {
214                GError* err = null;
215               
216                auto retStr = g_resolver_lookup_by_address_finish(gResolver, (result is null) ? null : result.getAsyncResultStruct(), &err);
217               
218                if (err !is null)
219                {
220                        throw new GException( new ErrorG(err) );
221                }
222               
223                scope(exit) Str.freeString(retStr);
224                return Str.toString(retStr);
225        }
226
227        /**
228         * Synchronously resolves @hostname to determine its associated IP
229         * address(es). @hostname may be an ASCII-only or UTF-8 hostname, or
230         * the textual form of an IP address (in which case this just becomes
231         * a wrapper around g_inet_address_new_from_string()).
232         *
233         * On success, g_resolver_lookup_by_name() will return a non-empty #GList of
234         * #GInetAddress, sorted in order of preference and guaranteed to not
235         * contain duplicates. That is, if using the result to connect to
236         * @hostname, you should attempt to connect to the first address
237         * first, then the second if the first fails, etc. If you are using
238         * the result to listen on a socket, it is appropriate to add each
239         * result using e.g. g_socket_listener_add_address().
240         *
241         * If the DNS resolution fails, @error (if non-%NULL) will be set to a
242         * value from #GResolverError and %NULL will be returned.
243         *
244         * If @cancellable is non-%NULL, it can be used to cancel the
245         * operation, in which case @error (if non-%NULL) will be set to
246         * %G_IO_ERROR_CANCELLED.
247         *
248         * If you are planning to connect to a socket on the resolved IP
249         * address, it may be easier to create a #GNetworkAddress and use its
250         * #GSocketConnectable interface.
251         *
252         * Params:
253         *     hostname = the hostname to look up
254         *     cancellable = a #GCancellable, or %NULL
255         *
256         * Returns: a non-empty #GList
257         *     of #GInetAddress, or %NULL on error. You
258         *     must unref each of the addresses and free the list when you are
259         *     done with it. (You can use g_resolver_free_addresses() to do this.)
260         *
261         * Since: 2.22
262         *
263         * Throws: GException on failure.
264         */
265        public ListG lookupByName(string hostname, Cancellable cancellable)
266        {
267                GError* err = null;
268               
269                auto p = g_resolver_lookup_by_name(gResolver, Str.toStringz(hostname), (cancellable is null) ? null : cancellable.getCancellableStruct(), &err);
270               
271                if (err !is null)
272                {
273                        throw new GException( new ErrorG(err) );
274                }
275               
276                if(p is null)
277                {
278                        return null;
279                }
280               
281                return new ListG(cast(GList*) p, true);
282        }
283
284        /**
285         * Begins asynchronously resolving @hostname to determine its
286         * associated IP address(es), and eventually calls @callback, which
287         * must call g_resolver_lookup_by_name_finish() to get the result.
288         * See g_resolver_lookup_by_name() for more details.
289         *
290         * Params:
291         *     hostname = the hostname to look up the address of
292         *     cancellable = a #GCancellable, or %NULL
293         *     callback = callback to call after resolution completes
294         *     userData = data for @callback
295         *
296         * Since: 2.22
297         */
298        public void lookupByNameAsync(string hostname, Cancellable cancellable, GAsyncReadyCallback callback, void* userData)
299        {
300                g_resolver_lookup_by_name_async(gResolver, Str.toStringz(hostname), (cancellable is null) ? null : cancellable.getCancellableStruct(), callback, userData);
301        }
302
303        /**
304         * Retrieves the result of a call to
305         * g_resolver_lookup_by_name_async().
306         *
307         * If the DNS resolution failed, @error (if non-%NULL) will be set to
308         * a value from #GResolverError. If the operation was cancelled,
309         * @error will be set to %G_IO_ERROR_CANCELLED.
310         *
311         * Params:
312         *     result = the result passed to your #GAsyncReadyCallback
313         *
314         * Returns: a #GList
315         *     of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name()
316         *     for more details.
317         *
318         * Since: 2.22
319         *
320         * Throws: GException on failure.
321         */
322        public ListG lookupByNameFinish(AsyncResultIF result)
323        {
324                GError* err = null;
325               
326                auto p = g_resolver_lookup_by_name_finish(gResolver, (result is null) ? null : result.getAsyncResultStruct(), &err);
327               
328                if (err !is null)
329                {
330                        throw new GException( new ErrorG(err) );
331                }
332               
333                if(p is null)
334                {
335                        return null;
336                }
337               
338                return new ListG(cast(GList*) p, true);
339        }
340
341        /**
342         * Synchronously performs a DNS record lookup for the given @rrname and returns
343         * a list of records as #GVariant tuples. See #GResolverRecordType for
344         * information on what the records contain for each @record_type.
345         *
346         * If the DNS resolution fails, @error (if non-%NULL) will be set to
347         * a value from #GResolverError and %NULL will be returned.
348         *
349         * If @cancellable is non-%NULL, it can be used to cancel the
350         * operation, in which case @error (if non-%NULL) will be set to
351         * %G_IO_ERROR_CANCELLED.
352         *
353         * Params:
354         *     rrname = the DNS name to lookup the record for
355         *     recordType = the type of DNS record to lookup
356         *     cancellable = a #GCancellable, or %NULL
357         *
358         * Returns: a non-empty #GList of
359         *     #GVariant, or %NULL on error. You must free each of the records and the list
360         *     when you are done with it. (You can use g_list_free_full() with
361         *     g_variant_unref() to do this.)
362         *
363         * Since: 2.34
364         *
365         * Throws: GException on failure.
366         */
367        public ListG lookupRecords(string rrname, GResolverRecordType recordType, Cancellable cancellable)
368        {
369                GError* err = null;
370               
371                auto p = g_resolver_lookup_records(gResolver, Str.toStringz(rrname), recordType, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err);
372               
373                if (err !is null)
374                {
375                        throw new GException( new ErrorG(err) );
376                }
377               
378                if(p is null)
379                {
380                        return null;
381                }
382               
383                return new ListG(cast(GList*) p, true);
384        }
385
386        /**
387         * Begins asynchronously performing a DNS lookup for the given
388         * @rrname, and eventually calls @callback, which must call
389         * g_resolver_lookup_records_finish() to get the final result. See
390         * g_resolver_lookup_records() for more details.
391         *
392         * Params:
393         *     rrname = the DNS name to lookup the record for
394         *     recordType = the type of DNS record to lookup
395         *     cancellable = a #GCancellable, or %NULL
396         *     callback = callback to call after resolution completes
397         *     userData = data for @callback
398         *
399         * Since: 2.34
400         */
401        public void lookupRecordsAsync(string rrname, GResolverRecordType recordType, Cancellable cancellable, GAsyncReadyCallback callback, void* userData)
402        {
403                g_resolver_lookup_records_async(gResolver, Str.toStringz(rrname), recordType, (cancellable is null) ? null : cancellable.getCancellableStruct(), callback, userData);
404        }
405
406        /**
407         * Retrieves the result of a previous call to
408         * g_resolver_lookup_records_async(). Returns a non-empty list of records as
409         * #GVariant tuples. See #GResolverRecordType for information on what the
410         * records contain.
411         *
412         * If the DNS resolution failed, @error (if non-%NULL) will be set to
413         * a value from #GResolverError. If the operation was cancelled,
414         * @error will be set to %G_IO_ERROR_CANCELLED.
415         *
416         * Params:
417         *     result = the result passed to your #GAsyncReadyCallback
418         *
419         * Returns: a non-empty #GList of
420         *     #GVariant, or %NULL on error. You must free each of the records and the list
421         *     when you are done with it. (You can use g_list_free_full() with
422         *     g_variant_unref() to do this.)
423         *
424         * Since: 2.34
425         *
426         * Throws: GException on failure.
427         */
428        public ListG lookupRecordsFinish(AsyncResultIF result)
429        {
430                GError* err = null;
431               
432                auto p = g_resolver_lookup_records_finish(gResolver, (result is null) ? null : result.getAsyncResultStruct(), &err);
433               
434                if (err !is null)
435                {
436                        throw new GException( new ErrorG(err) );
437                }
438               
439                if(p is null)
440                {
441                        return null;
442                }
443               
444                return new ListG(cast(GList*) p, true);
445        }
446
447        /**
448         * Synchronously performs a DNS SRV lookup for the given @service and
449         * @protocol in the given @domain and returns an array of #GSrvTarget.
450         * @domain may be an ASCII-only or UTF-8 hostname. Note also that the
451         * @service and @protocol arguments do not include the leading underscore
452         * that appears in the actual DNS entry.
453         *
454         * On success, g_resolver_lookup_service() will return a non-empty #GList of
455         * #GSrvTarget, sorted in order of preference. (That is, you should
456         * attempt to connect to the first target first, then the second if
457         * the first fails, etc.)
458         *
459         * If the DNS resolution fails, @error (if non-%NULL) will be set to
460         * a value from #GResolverError and %NULL will be returned.
461         *
462         * If @cancellable is non-%NULL, it can be used to cancel the
463         * operation, in which case @error (if non-%NULL) will be set to
464         * %G_IO_ERROR_CANCELLED.
465         *
466         * If you are planning to connect to the service, it is usually easier
467         * to create a #GNetworkService and use its #GSocketConnectable
468         * interface.
469         *
470         * Params:
471         *     service = the service type to look up (eg, "ldap")
472         *     protocol = the networking protocol to use for @service (eg, "tcp")
473         *     domain = the DNS domain to look up the service in
474         *     cancellable = a #GCancellable, or %NULL
475         *
476         * Returns: a non-empty #GList of
477         *     #GSrvTarget, or %NULL on error. You must free each of the targets and the
478         *     list when you are done with it. (You can use g_resolver_free_targets() to do
479         *     this.)
480         *
481         * Since: 2.22
482         *
483         * Throws: GException on failure.
484         */
485        public ListG lookupService(string service, string protocol, string domain, Cancellable cancellable)
486        {
487                GError* err = null;
488               
489                auto p = g_resolver_lookup_service(gResolver, Str.toStringz(service), Str.toStringz(protocol), Str.toStringz(domain), (cancellable is null) ? null : cancellable.getCancellableStruct(), &err);
490               
491                if (err !is null)
492                {
493                        throw new GException( new ErrorG(err) );
494                }
495               
496                if(p is null)
497                {
498                        return null;
499                }
500               
501                return new ListG(cast(GList*) p, true);
502        }
503
504        /**
505         * Begins asynchronously performing a DNS SRV lookup for the given
506         * @service and @protocol in the given @domain, and eventually calls
507         * @callback, which must call g_resolver_lookup_service_finish() to
508         * get the final result. See g_resolver_lookup_service() for more
509         * details.
510         *
511         * Params:
512         *     service = the service type to look up (eg, "ldap")
513         *     protocol = the networking protocol to use for @service (eg, "tcp")
514         *     domain = the DNS domain to look up the service in
515         *     cancellable = a #GCancellable, or %NULL
516         *     callback = callback to call after resolution completes
517         *     userData = data for @callback
518         *
519         * Since: 2.22
520         */
521        public void lookupServiceAsync(string service, string protocol, string domain, Cancellable cancellable, GAsyncReadyCallback callback, void* userData)
522        {
523                g_resolver_lookup_service_async(gResolver, Str.toStringz(service), Str.toStringz(protocol), Str.toStringz(domain), (cancellable is null) ? null : cancellable.getCancellableStruct(), callback, userData);
524        }
525
526        /**
527         * Retrieves the result of a previous call to
528         * g_resolver_lookup_service_async().
529         *
530         * If the DNS resolution failed, @error (if non-%NULL) will be set to
531         * a value from #GResolverError. If the operation was cancelled,
532         * @error will be set to %G_IO_ERROR_CANCELLED.
533         *
534         * Params:
535         *     result = the result passed to your #GAsyncReadyCallback
536         *
537         * Returns: a non-empty #GList of
538         *     #GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more
539         *     details.
540         *
541         * Since: 2.22
542         *
543         * Throws: GException on failure.
544         */
545        public ListG lookupServiceFinish(AsyncResultIF result)
546        {
547                GError* err = null;
548               
549                auto p = g_resolver_lookup_service_finish(gResolver, (result is null) ? null : result.getAsyncResultStruct(), &err);
550               
551                if (err !is null)
552                {
553                        throw new GException( new ErrorG(err) );
554                }
555               
556                if(p is null)
557                {
558                        return null;
559                }
560               
561                return new ListG(cast(GList*) p, true);
562        }
563
564        /**
565         * Sets @resolver to be the application's default resolver (reffing
566         * @resolver, and unreffing the previous default resolver, if any).
567         * Future calls to g_resolver_get_default() will return this resolver.
568         *
569         * This can be used if an application wants to perform any sort of DNS
570         * caching or "pinning"; it can implement its own #GResolver that
571         * calls the original default resolver for DNS operations, and
572         * implements its own cache policies on top of that, and then set
573         * itself as the default resolver for all later code to use.
574         *
575         * Since: 2.22
576         */
577        public void setDefault()
578        {
579                g_resolver_set_default(gResolver);
580        }
581
582        protected class OnReloadDelegateWrapper
583        {
584                static OnReloadDelegateWrapper[] listeners;
585                void delegate(Resolver) dlg;
586                gulong handlerId;
587               
588                this(void delegate(Resolver) dlg)
589                {
590                        this.dlg = dlg;
591                        this.listeners ~= this;
592                }
593               
594                void remove(OnReloadDelegateWrapper source)
595                {
596                        foreach(index, wrapper; listeners)
597                        {
598                                if (wrapper.handlerId == source.handlerId)
599                                {
600                                        listeners[index] = null;
601                                        listeners = std.algorithm.remove(listeners, index);
602                                        break;
603                                }
604                        }
605                }
606        }
607
608        /**
609         * Emitted when the resolver notices that the system resolver
610         * configuration has changed.
611         */
612        gulong addOnReload(void delegate(Resolver) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
613        {
614                auto wrapper = new OnReloadDelegateWrapper(dlg);
615                wrapper.handlerId = Signals.connectData(
616                        this,
617                        "reload",
618                        cast(GCallback)&callBackReload,
619                        cast(void*)wrapper,
620                        cast(GClosureNotify)&callBackReloadDestroy,
621                        connectFlags);
622                return wrapper.handlerId;
623        }
624       
625        extern(C) static void callBackReload(GResolver* resolverStruct, OnReloadDelegateWrapper wrapper)
626        {
627                wrapper.dlg(wrapper.outer);
628        }
629       
630        extern(C) static void callBackReloadDestroy(OnReloadDelegateWrapper wrapper, GClosure* closure)
631        {
632                wrapper.remove(wrapper);
633        }
634}
Note: See TracBrowser for help on using the repository browser.