2 * Copyright (c) 2002 Apple Computer, Inc. All rights reserved.
4 * @APPLE_LICENSE_HEADER_START@
6 * Portions Copyright (c) 2002 Apple Computer, Inc. All Rights
7 * Reserved. This file contains Original Code and/or Modifications of
8 * Original Code as defined in and that are subject to the Apple Public
9 * Source License Version 1.1 (the "License"). You may not use this file
10 * except in compliance with the License. Please obtain a copy of the
11 * License at http://www.apple.com/publicsource and read it before using
14 * The Original Code and all software distributed under the License are
15 * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
16 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
17 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE OR NON- INFRINGEMENT. Please see the
19 * License for the specific language governing rights and limitations
22 * @APPLE_LICENSE_HEADER_END@
25 #ifndef _NETDB_ASYNC_H_
26 #define _NETDB_ASYNC_H_
28 #include <sys/cdefs.h>
29 #include <mach/mach.h>
32 #define gethostbyname_async_handle_reply gethostbyname_async_handleReply
33 #define gethostbyaddr_async_handle_reply gethostbyaddr_async_handleReply
34 #define getipnodebyaddr_async_handle_reply getipnodebyaddr_async_handleReply
35 #define getipnodebyname_async_handle_reply getipnodebyname_async_handleReply
37 /* SPI for parallel / fast getaddrinfo */
38 #define AI_PARALLEL 0x00000008
43 * Private asynchronous lookup API
47 * Cancel an outstanding call and free its resources.
49 extern void lu_async_call_cancel(mach_port_t p
);
52 * Make an asynchronous lookupd call.
53 * Sends data buffer to lookupd and returns a port.
54 * The buffer must be encoded for lookupd.
56 extern kern_return_t
lu_async_start(mach_port_t
*p
, uint32_t proc
, const char *buf
, uint32_t len
, void *callback
, void *context
);
57 extern kern_return_t
lu_async_send(mach_port_t
*p
, uint32_t proc
, const char *buf
, uint32_t len
);
60 * Receive a reply for an asynchronous lookupd call.
61 * Receives the reply message and gets a raw (undecoded) data buffer.
63 extern kern_return_t
lu_async_receive(mach_port_t p
, char **buf
, uint32_t *len
);
66 * Takes a reply message and provides the callback, context, and raw data buffers.
67 * This routine does not invoke the callback. Type-specific asynchronous
68 * routines built on top of this API will decode the data buffer and invoke
69 * the callback routine.
71 extern int lu_async_handle_reply(void *msg
, char **buf
, uint32_t *len
, void **callback
, void **context
);
75 * Type-specific routines.
81 typedef void (*getaddrinfo_async_callback
)(int32_t status
, struct addrinfo
*res
, void *context
);
82 int32_t getaddrinfo_async_start(mach_port_t
*p
, const char *nodename
, const char *servname
, const struct addrinfo
*hints
, getaddrinfo_async_callback callback
, void *context
);
83 int32_t getaddrinfo_async_send(mach_port_t
*p
, const char *nodename
, const char *servname
, const struct addrinfo
*hints
);
84 int32_t getaddrinfo_async_receive(mach_port_t p
, struct addrinfo
**res
);
85 int32_t getaddrinfo_async_handle_reply(void *msg
);
91 typedef void (*getnameinfo_async_callback
)(int32_t status
, char *host
, char *serv
, void *context
);
92 int32_t getnameinfo_async_start(mach_port_t
*p
, const struct sockaddr
*sa
, size_t salen
, int flags
, getnameinfo_async_callback callback
, void *context
);
93 int32_t getnameinfo_async_send(mach_port_t
*p
, const struct sockaddr
*sa
, size_t salen
, int flags
);
94 int32_t getnameinfo_async_receive(mach_port_t p
, char **host
, char **serv
);
95 int32_t getnameinfo_async_handle_reply(void *msg
);
100 typedef void (*dns_async_callback
)(int32_t status
, char *buf
, uint32_t len
, struct sockaddr
*from
, int fromlen
, void *context
);
101 int32_t dns_async_start(mach_port_t
*p
, const char *name
, uint16_t dnsclass
, uint16_t dnstype
, uint32_t do_search
, dns_async_callback callback
, void *context
);
102 int32_t dns_async_send(mach_port_t
*p
, const char *name
, uint16_t dnsclass
, uint16_t dnstype
, uint32_t do_search
);
103 int32_t dns_async_receive(mach_port_t p
, char **buf
, uint32_t *len
, struct sockaddr
**from
, uint32_t *fromlen
);
104 int32_t dns_async_handle_reply(void *msg
);
107 * Host lookup asynchronous API
108 * These routines don't use the asynchronous lookupd access support
109 * described above. There will eventually be converted.
110 * The API is syntactically similar.
114 @typedef gethostbyaddr_async_callback
115 @discussion Type of the callback function used when a
116 gethostbyaddr_async_start() request is delivered.
117 @param hent The resolved host entry.
118 @param context The context provided when the request
121 typedef void (*gethostbyaddr_async_callback
)(struct hostent
*hent
, void *context
);
124 @function gethostbyaddr_async_start
125 @description Asynchronously resolves an Internet address
126 @param addr The address to be resolved.
127 @param len The length, in bytes, of the address.
129 @param callout The function to be called when the specified
130 address has been resolved.
131 @param context A user specified context which will be passed
132 to the callout function.
133 @result A mach reply port which will be sent a message when
134 the addr resolution has completed. This message
135 should be passed to the gethostbyaddr_async_handleReply
136 function. A NULL value indicates that no address
137 was specified or some other error occurred which
138 prevented the resolution from being started.
141 gethostbyaddr_async_start(const char *addr
, int len
, int type
, gethostbyaddr_async_callback callout
, void *context
);
144 @function gethostbyaddr_async_cancel
145 @description Cancel an asynchronous request currently in progress.
146 @param port The mach reply port associated with the request to be cancelled.
148 void gethostbyaddr_async_cancel(mach_port_t port
);
151 @function gethostbyaddr_async_handleReply
152 @description This function should be called with the Mach message sent
153 to the port returned by the call to gethostbyaddr_async_start.
154 The reply message will be interpreted and will result in a
155 call to the specified callout function.
156 @param replyMsg The Mach message.
158 void gethostbyaddr_async_handleReply(void *replyMsg
);
161 @typedef gethostbyname_async_callback
162 @discussion Type of the callback function used when a
163 gethostbyname_async_start() request is delivered.
164 @param hent The resolved host entry.
165 @param context The context provided when the request was initiated.
167 typedef void (*gethostbyname_async_callback
)(struct hostent
*hent
, void *context
);
170 @function gethostbyname_async_start
171 @description Asynchronously resolves a hostname
172 @param name The hostname to be resolved.
173 @param callout The function to be called when the specified
174 hostname has been resolved.
175 @param context A user specified context which will be passed
176 to the callout function.
177 @result A mach reply port which will be sent a message when
178 the name resolution has completed. This message
179 should be passed to the gethostbyname_async_handleReply
180 function. A NULL value indicates that no hostname
181 was specified or some other error occurred which
182 prevented the resolution from being started.
184 mach_port_t
gethostbyname_async_start(const char *name
, gethostbyname_async_callback callout
, void *context
);
187 @function gethostbyname_async_cancel
188 @description Cancel an asynchronous request currently in progress.
189 @param port The mach reply port associated with the request to be cancelled.
191 void gethostbyname_async_cancel(mach_port_t port
);
194 @function gethostbyname_async_handleReply
195 @description This function should be called with the Mach message sent
196 to the port returned by the call to gethostbyname_async_start.
197 The reply message will be interpreted and will result in a
198 call to the specified callout function.
199 @param replyMsg The Mach message.
201 void gethostbyname_async_handleReply(void *replyMsg
);
204 @typedef getipnodebyaddr_async_callback
205 @discussion Type of the callback function used when a
206 getipnodebyaddr_async_start() request is delivered.
207 @param hent The resolved host entry. If not NULL, the caller
208 must call freehostent() on the host entry.
209 @param error If error code if the resolved host entry is NULL
210 @param context The context provided when the request was initiated.
212 typedef void (*getipnodebyaddr_async_callback
)(struct hostent
*hent
, int error
, void *context
);
215 @function getipnodebyaddr_async_start
216 @description Asynchronously resolves an Internet address
217 @param addr The address to be resolved.
218 @param len The length, in bytes, of the address.
219 @param af The address family
221 @param callout The function to be called when the specified
222 address has been resolved.
223 @param context A user specified context which will be passed
224 to the callout function.
225 @result A mach reply port which will be sent a message when
226 the addr resolution has completed. This message
227 should be passed to the getipnodebyaddr_async_handleReply
228 function. A NULL value indicates that no address
229 was specified or some other error occurred which
230 prevented the resolution from being started.
232 mach_port_t
getipnodebyaddr_async_start(const void *addr
, size_t len
, int af
, int *error
, getipnodebyaddr_async_callback callout
, void *context
);
235 @function getipnodebyaddr_async_cancel
236 @description Cancel an asynchronous request currently in progress.
237 @param port The mach reply port associated with the request to be cancelled.
239 void getipnodebyaddr_async_cancel(mach_port_t port
);
242 @function getipnodebyaddr_async_handleReply
243 @description This function should be called with the Mach message sent
244 to the port returned by the call to getipnodebyaddr_async_start.
245 The reply message will be interpreted and will result in a
246 call to the specified callout function.
247 @param replyMsg The Mach message.
249 void getipnodebyaddr_async_handleReply(void *replyMsg
);
253 @typedef getipnodebyname_async_callback
254 @discussion Type of the callback function used when a
255 getipnodebyname_async_start() request is delivered.
256 @param hent The resolved host entry. If not NULL, the caller
257 must call freehostent() on the host entry.
258 @param error If error code if the resolved host entry is NULL
259 @param context The context provided when the request was initiated.
261 typedef void (*getipnodebyname_async_callback
)(struct hostent
*hent
, int error
, void *context
);
264 @function getipnodebyname_async_start
265 @description Asynchronously resolves a hostname
266 @param name The hostname to be resolved.
270 @param callout The function to be called when the specified
271 hostname has been resolved.
272 @param context A user specified context which will be passed
273 to the callout function.
274 @result A mach reply port which will be sent a message when
275 the name resolution has completed. This message
276 should be passed to the getipnodebyname_async_handleReply
277 function. A NULL value indicates that no hostname
278 was specified or some other error occurred which
279 prevented the resolution from being started.
281 mach_port_t
getipnodebyname_async_start(const char *name
, int af
, int flags
, int *error
, getipnodebyname_async_callback callout
, void *context
);
284 @function getipnodebyname_async_cancel
285 @description Cancel an asynchronous request currently in progress.
286 @param port The mach reply port associated with the request to be cancelled.
288 void getipnodebyname_async_cancel(mach_port_t port
);
291 @function getipnodebyname_async_handleReply
292 @description This function should be called with the Mach message sent
293 to the port returned by the call to getipnodebyname_async_start.
294 The reply message will be interpreted and will result in a
295 call to the specified callout function.
296 @param replyMsg The Mach message.
298 void getipnodebyname_async_handleReply(void *replyMsg
);
302 #endif /* !_NETDB_ASYNC_H_ */