lookup.subproj/netdb_async.h

   1 /*
   2  * Copyright (c) 2002 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   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
  12  * this file.
  13  *
  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
  20  * under the License.
  21  *
  22  * @APPLE_LICENSE_HEADER_END@
  23  */
  24
  25 #ifndef _NETDB_ASYNC_H_
  26 #define _NETDB_ASYNC_H_
  27
  28 #include <sys/cdefs.h>
  29 #include <mach/mach.h>
  30 #include <netdb.h>
  31
  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
  36
  37 /* SPI for parallel / fast getaddrinfo */
  38 #define AI_PARALLEL     0x00000008
  39
  40 __BEGIN_DECLS
  41
  42 /*
  43  * Private asynchronous lookup API
  44  */
  45
  46 /*
  47  * Cancel an outstanding call and free its resources.
  48  */
  49 extern void lu_async_call_cancel(mach_port_t p);
  50
  51 /*
  52  * Make an asynchronous lookupd call.
  53  * Sends data buffer to lookupd and returns a port.
  54  * The buffer must be encoded for lookupd.
  55  */
  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);
  58
  59 /*
  60  * Receive a reply for an asynchronous lookupd call.
  61  * Receives the reply message and gets a raw (undecoded) data buffer.
  62  */
  63 extern kern_return_t lu_async_receive(mach_port_t p, char **buf, uint32_t *len);
  64
  65 /*
  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.
  70  */
  71 extern int lu_async_handle_reply(void *msg, char **buf, uint32_t *len, void **callback, void **context);
  72
  73
  74 /*
  75  * Type-specific routines.
  76  */
  77
  78 /*
  79  * getaddrinfo
  80  */
  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);
  86
  87
  88 /*
  89  * getnameinfo
  90  */
  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);
  96
  97 /*
  98  * DNS
  99  */
 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);
 105
 106 /*
 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.
 111  */
 112
 113 /*
 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
 119         was initiated.
 120  */
 121 typedef void (*gethostbyaddr_async_callback)(struct hostent *hent, void *context);
 122
 123 /*!
 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.
 128  @param type
 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.
 139  */
 140 mach_port_t
 141 gethostbyaddr_async_start(const char *addr, int len, int type, gethostbyaddr_async_callback callout, void *context);
 142
 143 /*!
 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.
 147  */
 148 void gethostbyaddr_async_cancel(mach_port_t port);
 149
 150 /*!
 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.
 157  */
 158 void gethostbyaddr_async_handleReply(void *replyMsg);
 159
 160 /*
 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.
 166  */
 167 typedef void (*gethostbyname_async_callback)(struct hostent *hent, void *context);
 168
 169 /*!
 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.
 183  */
 184 mach_port_t gethostbyname_async_start(const char *name, gethostbyname_async_callback callout, void *context);
 185
 186 /*!
 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.
 190  */
 191 void gethostbyname_async_cancel(mach_port_t port);
 192
 193 /*!
 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.
 200  */
 201 void gethostbyname_async_handleReply(void *replyMsg);
 202
 203 /*
 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.
 211  */
 212 typedef void (*getipnodebyaddr_async_callback)(struct hostent *hent, int error, void *context);
 213
 214 /*!
 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
 220  @param error
 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.
 231  */
 232 mach_port_t getipnodebyaddr_async_start(const void *addr, size_t len, int af, int *error, getipnodebyaddr_async_callback callout, void *context);
 233
 234 /*!
 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.
 238  */
 239 void getipnodebyaddr_async_cancel(mach_port_t port);
 240
 241 /*!
 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.
 248  */
 249 void getipnodebyaddr_async_handleReply(void *replyMsg);
 250
 251
 252 /*
 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.
 260  */
 261 typedef void (*getipnodebyname_async_callback)(struct hostent *hent, int error, void *context);
 262
 263 /*!
 264  @function getipnodebyname_async_start
 265  @description Asynchronously resolves a hostname
 266  @param name The hostname to be resolved.
 267  @param af
 268  @param flags
 269  @param error
 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.
 280  */
 281 mach_port_t getipnodebyname_async_start(const char *name, int af, int flags, int *error, getipnodebyname_async_callback callout, void *context);
 282
 283 /*!
 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.
 287  */
 288 void getipnodebyname_async_cancel(mach_port_t port);
 289
 290 /*!
 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.
 297  */
 298 void getipnodebyname_async_handleReply(void *replyMsg);
 299
 300 __END_DECLS
 301
 302 #endif /* !_NETDB_ASYNC_H_ */