1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
|
/* GIO - GLib Input, Output and Streaming Library
*
* Copyright (C) 2008 Red Hat, Inc.
*
* SPDX-License-Identifier: LGPL-2.1-or-later
*
* 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, see <http://www.gnu.org/licenses/>.
*/
#include "config.h"
#include "gsocketaddressenumerator.h"
#include "glibintl.h"
#include "gtask.h"
/**
* SECTION:gsocketaddressenumerator
* @short_description: Enumerator for socket addresses
* @include: gio/gio.h
*
* #GSocketAddressEnumerator is an enumerator type for #GSocketAddress
* instances. It is returned by enumeration functions such as
* g_socket_connectable_enumerate(), which returns a #GSocketAddressEnumerator
* to list each #GSocketAddress which could be used to connect to that
* #GSocketConnectable.
*
* Enumeration is typically a blocking operation, so the asynchronous methods
* g_socket_address_enumerator_next_async() and
* g_socket_address_enumerator_next_finish() should be used where possible.
*
* Each #GSocketAddressEnumerator can only be enumerated once. Once
* g_socket_address_enumerator_next() has returned %NULL, further
* enumeration with that #GSocketAddressEnumerator is not possible, and it can
* be unreffed.
*/
G_DEFINE_ABSTRACT_TYPE (GSocketAddressEnumerator, g_socket_address_enumerator, G_TYPE_OBJECT)
static void g_socket_address_enumerator_real_next_async (GSocketAddressEnumerator *enumerator,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
static GSocketAddress *g_socket_address_enumerator_real_next_finish (GSocketAddressEnumerator *enumerator,
GAsyncResult *result,
GError **error);
static void
g_socket_address_enumerator_init (GSocketAddressEnumerator *enumerator)
{
}
static void
g_socket_address_enumerator_class_init (GSocketAddressEnumeratorClass *enumerator_class)
{
enumerator_class->next_async = g_socket_address_enumerator_real_next_async;
enumerator_class->next_finish = g_socket_address_enumerator_real_next_finish;
}
/**
* g_socket_address_enumerator_next:
* @enumerator: a #GSocketAddressEnumerator
* @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
* @error: a #GError.
*
* Retrieves the next #GSocketAddress from @enumerator. Note that this
* may block for some amount of time. (Eg, a #GNetworkAddress may need
* to do a DNS lookup before it can return an address.) Use
* g_socket_address_enumerator_next_async() if you need to avoid
* blocking.
*
* If @enumerator is expected to yield addresses, but for some reason
* is unable to (eg, because of a DNS error), then the first call to
* g_socket_address_enumerator_next() will return an appropriate error
* in *@error. However, if the first call to
* g_socket_address_enumerator_next() succeeds, then any further
* internal errors (other than @cancellable being triggered) will be
* ignored.
*
* Returns: (transfer full) (nullable): a #GSocketAddress (owned by the caller), or %NULL on
* error (in which case *@error will be set) or if there are no
* more addresses.
*/
GSocketAddress *
g_socket_address_enumerator_next (GSocketAddressEnumerator *enumerator,
GCancellable *cancellable,
GError **error)
{
GSocketAddressEnumeratorClass *klass;
g_return_val_if_fail (G_IS_SOCKET_ADDRESS_ENUMERATOR (enumerator), NULL);
klass = G_SOCKET_ADDRESS_ENUMERATOR_GET_CLASS (enumerator);
return (* klass->next) (enumerator, cancellable, error);
}
/* Default implementation just calls the synchronous method; this can
* be used if the implementation already knows all of its addresses,
* and so the synchronous method will never block.
*/
static void
g_socket_address_enumerator_real_next_async (GSocketAddressEnumerator *enumerator,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data)
{
GTask *task;
GSocketAddress *address;
GError *error = NULL;
task = g_task_new (enumerator, NULL, callback, user_data);
g_task_set_source_tag (task, g_socket_address_enumerator_real_next_async);
address = g_socket_address_enumerator_next (enumerator, cancellable, &error);
if (error)
g_task_return_error (task, error);
else
g_task_return_pointer (task, address, g_object_unref);
g_object_unref (task);
}
/**
* g_socket_address_enumerator_next_async:
* @enumerator: a #GSocketAddressEnumerator
* @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
* @callback: (scope async) (closure user_data): a #GAsyncReadyCallback to call
* when the request is satisfied
* @user_data: the data to pass to callback function
*
* Asynchronously retrieves the next #GSocketAddress from @enumerator
* and then calls @callback, which must call
* g_socket_address_enumerator_next_finish() to get the result.
*
* It is an error to call this multiple times before the previous callback has finished.
*/
void
g_socket_address_enumerator_next_async (GSocketAddressEnumerator *enumerator,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data)
{
GSocketAddressEnumeratorClass *klass;
g_return_if_fail (G_IS_SOCKET_ADDRESS_ENUMERATOR (enumerator));
klass = G_SOCKET_ADDRESS_ENUMERATOR_GET_CLASS (enumerator);
(* klass->next_async) (enumerator, cancellable, callback, user_data);
}
static GSocketAddress *
g_socket_address_enumerator_real_next_finish (GSocketAddressEnumerator *enumerator,
GAsyncResult *result,
GError **error)
{
g_return_val_if_fail (g_task_is_valid (result, enumerator), NULL);
return g_task_propagate_pointer (G_TASK (result), error);
}
/**
* g_socket_address_enumerator_next_finish:
* @enumerator: a #GSocketAddressEnumerator
* @result: a #GAsyncResult
* @error: a #GError
*
* Retrieves the result of a completed call to
* g_socket_address_enumerator_next_async(). See
* g_socket_address_enumerator_next() for more information about
* error handling.
*
* Returns: (transfer full) (nullable): a #GSocketAddress (owned by the caller), or %NULL on
* error (in which case *@error will be set) or if there are no
* more addresses.
*/
GSocketAddress *
g_socket_address_enumerator_next_finish (GSocketAddressEnumerator *enumerator,
GAsyncResult *result,
GError **error)
{
GSocketAddressEnumeratorClass *klass;
g_return_val_if_fail (G_IS_SOCKET_ADDRESS_ENUMERATOR (enumerator), NULL);
klass = G_SOCKET_ADDRESS_ENUMERATOR_GET_CLASS (enumerator);
return (* klass->next_finish) (enumerator, result, error);
}
|
