lookup.subproj/netdb_async.h

   1 /*
   2  * Copyright (c) 2002 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
   7  *
   8  * This file contains Original Code and/or Modifications of Original Code
   9  * as defined in and that are subject to the Apple Public Source License
  10  * Version 2.0 (the 'License'). You may not use this file except in
  11  * compliance with the License. Please obtain a copy of the License at
  12  * http://www.opensource.apple.com/apsl/ and read it before using this
  13  * file.
  14  *
  15  * The Original Code and all software distributed under the License are
  16  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  17  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  18  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  20  * Please see the License for the specific language governing rights and
  21  * limitations under the License.
  22  *
  23  * @APPLE_LICENSE_HEADER_END@
  24  */
  25
  26 #ifndef _NETDB_ASYNC_H_
  27 #define _NETDB_ASYNC_H_
  28
  29 #include <sys/cdefs.h>
  30 #include <mach/mach.h>
  31 #include <netdb.h>
  32
  33 #define gethostbyname_async_handle_reply gethostbyname_async_handleReply
  34 #define gethostbyaddr_async_handle_reply gethostbyaddr_async_handleReply
  35 #define getipnodebyaddr_async_handle_reply getipnodebyaddr_async_handleReply
  36 #define getipnodebyname_async_handle_reply getipnodebyname_async_handleReply
  37
  38 __BEGIN_DECLS
  39
  40 /*
  41  * Private asynchronous lookup API
  42  */
  43
  44 /*
  45  * Cancel an outstanding call and free its resources.
  46  */
  47 extern void lu_async_call_cancel(mach_port_t p);
  48
  49 /*
  50  * Make an asynchronous lookupd call.
  51  * Sends data buffer to lookupd and returns a port.
  52  * The buffer must be encoded for lookupd.
  53  */
  54 extern kern_return_t lu_async_start(mach_port_t *p, uint32_t proc, const char *buf, uint32_t len, void *callback, void *context);
  55 extern kern_return_t lu_async_send(mach_port_t *p, uint32_t proc, const char *buf, uint32_t len);
  56
  57 /*
  58  * Receive a reply for an asynchronous lookupd call.
  59  * Receives the reply message and gets a raw (undecoded) data buffer.
  60  */
  61 extern kern_return_t lu_async_receive(mach_port_t p, char **buf, uint32_t *len);
  62
  63 /*
  64  * Takes a reply message and provides the callback, context, and raw data buffers.
  65  * This routine does not invoke the callback.  Type-specific asynchronous
  66  * routines built on top of this API will decode the data buffer and invoke
  67  * the callback routine.
  68  */
  69 extern int lu_async_handle_reply(void *msg, char **buf, uint32_t *len, void **callback, void **context);
  70
  71
  72 /*
  73  * Type-specific routines.
  74  */
  75
  76 /*
  77  * getaddrinfo
  78  */
  79 typedef void (*getaddrinfo_async_callback)(int32_t status, struct addrinfo *res, void *context);
  80 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);
  81 int32_t getaddrinfo_async_send(mach_port_t *p, const char *nodename, const char *servname, const struct addrinfo *hints);
  82 int32_t getaddrinfo_async_receive(mach_port_t p, struct addrinfo **res);
  83 int32_t getaddrinfo_async_handle_reply(void *msg);
  84
  85
  86 /*
  87  * getnameinfo
  88  */
  89 typedef void (*getnameinfo_async_callback)(int32_t status, char *host, char *serv, void *context);
  90 int32_t getnameinfo_async_start(mach_port_t *p, const struct sockaddr *sa, size_t salen, int flags, getnameinfo_async_callback callback, void *context);
  91 int32_t getnameinfo_async_send(mach_port_t *p, const struct sockaddr *sa, size_t salen, int flags);
  92 int32_t getnameinfo_async_receive(mach_port_t p, char **host, char **serv);
  93 int32_t getnameinfo_async_handle_reply(void *msg);
  94
  95 /*
  96  * DNS
  97  */
  98 typedef void (*dns_async_callback)(int32_t status, char *buf, uint32_t len, struct sockaddr *from, int fromlen, void *context);
  99 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);
 100 int32_t dns_async_send(mach_port_t *p, const char *name, uint16_t dnsclass, uint16_t dnstype, uint32_t do_search);
 101 int32_t dns_async_receive(mach_port_t p, char **buf, uint32_t *len, struct sockaddr **from, uint32_t *fromlen);
 102 int32_t dns_async_handle_reply(void *msg);
 103
 104 /*
 105  * Host lookup asynchronous API
 106  * These routines don't use the asynchronous lookupd access support
 107  * described above.  There will eventually be converted.
 108  * The API is syntactically similar.
 109  */
 110
 111 /*
 112  @typedef gethostbyaddr_async_callback
 113  @discussion Type of the callback function used when a
 114         gethostbyaddr_async_start() request is delivered.
 115  @param hent The resolved host entry.
 116  @param context The context provided when the request
 117         was initiated.
 118  */
 119 typedef void (*gethostbyaddr_async_callback)(struct hostent *hent, void *context);
 120
 121 /*!
 122  @function gethostbyaddr_async_start
 123  @description Asynchronously resolves an Internet address
 124  @param addr The address to be resolved.
 125  @param len The length, in bytes, of the address.
 126  @param type
 127  @param callout The function to be called when the specified
 128         address has been resolved.
 129  @param context A user specified context which will be passed
 130         to the callout function.
 131  @result A mach reply port which will be sent a message when
 132         the addr resolution has completed. This message
 133         should be passed to the gethostbyaddr_async_handleReply
 134         function. A NULL value indicates that no address
 135         was specified or some other error occurred which
 136         prevented the resolution from being started.
 137  */
 138 mach_port_t
 139 gethostbyaddr_async_start(const char *addr, int len, int type, gethostbyaddr_async_callback callout, void *context);
 140
 141 /*!
 142  @function gethostbyaddr_async_cancel
 143  @description Cancel an asynchronous request currently in progress.
 144  @param port The mach reply port associated with the request to be cancelled.
 145  */
 146 void gethostbyaddr_async_cancel(mach_port_t port);
 147
 148 /*!
 149  @function gethostbyaddr_async_handleReply
 150  @description This function should be called with the Mach message sent
 151         to the port returned by the call to gethostbyaddr_async_start.
 152         The reply message will be interpreted and will result in a
 153         call to the specified callout function.
 154  @param replyMsg The Mach message.
 155  */
 156 void gethostbyaddr_async_handleReply(void *replyMsg);
 157
 158 /*
 159  @typedef gethostbyname_async_callback
 160  @discussion Type of the callback function used when a
 161         gethostbyname_async_start() request is delivered.
 162  @param hent The resolved host entry.
 163  @param context The context provided when the request was initiated.
 164  */
 165 typedef void (*gethostbyname_async_callback)(struct hostent *hent, void *context);
 166
 167 /*!
 168  @function gethostbyname_async_start
 169  @description Asynchronously resolves a hostname
 170  @param name The hostname to be resolved.
 171  @param callout The function to be called when the specified
 172         hostname has been resolved.
 173  @param context A user specified context which will be passed
 174         to the callout function.
 175  @result A mach reply port which will be sent a message when
 176         the name resolution has completed. This message
 177         should be passed to the gethostbyname_async_handleReply
 178         function. A NULL value indicates that no hostname
 179         was specified or some other error occurred which
 180         prevented the resolution from being started.
 181  */
 182 mach_port_t gethostbyname_async_start(const char *name, gethostbyname_async_callback callout, void *context);
 183
 184 /*!
 185  @function gethostbyname_async_cancel
 186  @description Cancel an asynchronous request currently in progress.
 187  @param port The mach reply port associated with the request to be cancelled.
 188  */
 189 void gethostbyname_async_cancel(mach_port_t port);
 190
 191 /*!
 192  @function gethostbyname_async_handleReply
 193  @description This function should be called with the Mach message sent
 194         to the port returned by the call to gethostbyname_async_start.
 195         The reply message will be interpreted and will result in a
 196         call to the specified callout function.
 197  @param replyMsg The Mach message.
 198  */
 199 void gethostbyname_async_handleReply(void *replyMsg);
 200
 201 /*
 202  @typedef getipnodebyaddr_async_callback
 203  @discussion Type of the callback function used when a
 204         getipnodebyaddr_async_start() request is delivered.
 205  @param hent The resolved host entry. If not NULL, the caller
 206         must call freehostent() on the host entry.
 207  @param error If error code if the resolved host entry is NULL
 208  @param context The context provided when the request was initiated.
 209  */
 210 typedef void (*getipnodebyaddr_async_callback)(struct hostent *hent, int error, void *context);
 211
 212 /*!
 213  @function getipnodebyaddr_async_start
 214  @description Asynchronously resolves an Internet address
 215  @param addr The address to be resolved.
 216  @param len The length, in bytes, of the address.
 217  @param af The address family
 218  @param error
 219  @param callout The function to be called when the specified
 220         address has been resolved.
 221  @param context A user specified context which will be passed
 222         to the callout function.
 223  @result A mach reply port which will be sent a message when
 224         the addr resolution has completed. This message
 225         should be passed to the getipnodebyaddr_async_handleReply
 226         function. A NULL value indicates that no address
 227         was specified or some other error occurred which
 228         prevented the resolution from being started.
 229  */
 230 mach_port_t getipnodebyaddr_async_start(const void *addr, size_t len, int af, int *error, getipnodebyaddr_async_callback callout, void *context);
 231
 232 /*!
 233  @function getipnodebyaddr_async_cancel
 234  @description Cancel an asynchronous request currently in progress.
 235  @param port The mach reply port associated with the request to be cancelled.
 236  */
 237 void getipnodebyaddr_async_cancel(mach_port_t port);
 238
 239 /*!
 240  @function getipnodebyaddr_async_handleReply
 241  @description This function should be called with the Mach message sent
 242         to the port returned by the call to getipnodebyaddr_async_start.
 243         The reply message will be interpreted and will result in a
 244         call to the specified callout function.
 245  @param replyMsg The Mach message.
 246  */
 247 void getipnodebyaddr_async_handleReply(void *replyMsg);
 248
 249
 250 /*
 251  @typedef getipnodebyname_async_callback
 252  @discussion Type of the callback function used when a
 253         getipnodebyname_async_start() request is delivered.
 254  @param hent The resolved host entry. If not NULL, the caller
 255         must call freehostent() on the host entry.
 256  @param error If error code if the resolved host entry is NULL
 257  @param context The context provided when the request was initiated.
 258  */
 259 typedef void (*getipnodebyname_async_callback)(struct hostent *hent, int error, void *context);
 260
 261 /*!
 262  @function getipnodebyname_async_start
 263  @description Asynchronously resolves a hostname
 264  @param name The hostname to be resolved.
 265  @param af
 266  @param flags
 267  @param error
 268  @param callout The function to be called when the specified
 269         hostname has been resolved.
 270  @param context A user specified context which will be passed
 271         to the callout function.
 272  @result A mach reply port which will be sent a message when
 273         the name resolution has completed. This message
 274         should be passed to the getipnodebyname_async_handleReply
 275         function. A NULL value indicates that no hostname
 276         was specified or some other error occurred which
 277         prevented the resolution from being started.
 278  */
 279 mach_port_t getipnodebyname_async_start(const char *name, int af, int flags, int *error, getipnodebyname_async_callback callout, void *context);
 280
 281 /*!
 282  @function getipnodebyname_async_cancel
 283  @description Cancel an asynchronous request currently in progress.
 284  @param port The mach reply port associated with the request to be cancelled.
 285  */
 286 void getipnodebyname_async_cancel(mach_port_t port);
 287
 288 /*!
 289  @function getipnodebyname_async_handleReply
 290  @description This function should be called with the Mach message sent
 291         to the port returned by the call to getipnodebyname_async_start.
 292         The reply message will be interpreted and will result in a
 293         call to the specified callout function.
 294  @param replyMsg The Mach message.
 295  */
 296 void getipnodebyname_async_handleReply(void *replyMsg);
 297
 298 __END_DECLS
 299
 300 #endif /* !_NETDB_ASYNC_H_ */