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 __BEGIN_DECLS
  38
  39 /*
  40  * Private asynchronous lookup API
  41  */
  42
  43 /*
  44  * Cancel an outstanding call and free its resources.
  45  */
  46 extern void lu_async_call_cancel(mach_port_t p);
  47
  48 /*
  49  * Make an asynchronous lookupd call.
  50  * Sends data buffer to lookupd and returns a port.
  51  * The buffer must be encoded for lookupd.
  52  */
  53 extern kern_return_t lu_async_start(mach_port_t *p, uint32_t proc, const char *buf, uint32_t len, void *callback, void *context);
  54 extern kern_return_t lu_async_send(mach_port_t *p, uint32_t proc, const char *buf, uint32_t len);
  55
  56 /*
  57  * Receive a reply for an asynchronous lookupd call.
  58  * Receives the reply message and gets a raw (undecoded) data buffer.
  59  */
  60 extern kern_return_t lu_async_receive(mach_port_t p, char **buf, uint32_t *len);
  61
  62 /*
  63  * Takes a reply message and provides the callback, context, and raw data buffers.
  64  * This routine does not invoke the callback.  Type-specific asynchronous
  65  * routines built on top of this API will decode the data buffer and invoke
  66  * the callback routine.
  67  */
  68 extern int lu_async_handle_reply(void *msg, char **buf, uint32_t *len, void **callback, void **context);
  69
  70
  71 /*
  72  * Type-specific routines.
  73  */
  74
  75 /*
  76  * getaddrinfo
  77  */
  78 typedef void (*getaddrinfo_async_callback)(int32_t status, struct addrinfo *res, void *context);
  79 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);
  80 int32_t getaddrinfo_async_send(mach_port_t *p, const char *nodename, const char *servname, const struct addrinfo *hints);
  81 int32_t getaddrinfo_async_receive(mach_port_t p, struct addrinfo **res);
  82 int32_t getaddrinfo_async_handle_reply(void *msg);
  83
  84
  85 /*
  86  * getnameinfo
  87  */
  88 typedef void (*getnameinfo_async_callback)(int32_t status, char *host, char *serv, void *context);
  89 int32_t getnameinfo_async_start(mach_port_t *p, const struct sockaddr *sa, size_t salen, int flags, getnameinfo_async_callback callback, void *context);
  90 int32_t getnameinfo_async_send(mach_port_t *p, const struct sockaddr *sa, size_t salen, int flags);
  91 int32_t getnameinfo_async_receive(mach_port_t p, char **host, char **serv);
  92 int32_t getnameinfo_async_handle_reply(void *msg);
  93
  94 /*
  95  * DNS
  96  */
  97 typedef void (*dns_async_callback)(int32_t status, char *buf, uint32_t len, struct sockaddr *from, int fromlen, void *context);
  98 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);
  99 int32_t dns_async_send(mach_port_t *p, const char *name, uint16_t dnsclass, uint16_t dnstype, uint32_t do_search);
 100 int32_t dns_async_receive(mach_port_t p, char **buf, uint32_t *len, struct sockaddr **from, uint32_t *fromlen);
 101 int32_t dns_async_handle_reply(void *msg);
 102
 103 /*
 104  * Host lookup asynchronous API
 105  * These routines don't use the asynchronous lookupd access support
 106  * described above.  There will eventually be converted.
 107  * The API is syntactically similar.
 108  */
 109
 110 /*
 111  @typedef gethostbyaddr_async_callback
 112  @discussion Type of the callback function used when a
 113         gethostbyaddr_async_start() request is delivered.
 114  @param hent The resolved host entry.
 115  @param context The context provided when the request
 116         was initiated.
 117  */
 118 typedef void (*gethostbyaddr_async_callback)(struct hostent *hent, void *context);
 119
 120 /*!
 121  @function gethostbyaddr_async_start
 122  @description Asynchronously resolves an Internet address
 123  @param addr The address to be resolved.
 124  @param len The length, in bytes, of the address.
 125  @param type
 126  @param callout The function to be called when the specified
 127         address has been resolved.
 128  @param context A user specified context which will be passed
 129         to the callout function.
 130  @result A mach reply port which will be sent a message when
 131         the addr resolution has completed. This message
 132         should be passed to the gethostbyaddr_async_handleReply
 133         function. A NULL value indicates that no address
 134         was specified or some other error occurred which
 135         prevented the resolution from being started.
 136  */
 137 mach_port_t
 138 gethostbyaddr_async_start(const char *addr, int len, int type, gethostbyaddr_async_callback callout, void *context);
 139
 140 /*!
 141  @function gethostbyaddr_async_cancel
 142  @description Cancel an asynchronous request currently in progress.
 143  @param port The mach reply port associated with the request to be cancelled.
 144  */
 145 void gethostbyaddr_async_cancel(mach_port_t port);
 146
 147 /*!
 148  @function gethostbyaddr_async_handleReply
 149  @description This function should be called with the Mach message sent
 150         to the port returned by the call to gethostbyaddr_async_start.
 151         The reply message will be interpreted and will result in a
 152         call to the specified callout function.
 153  @param replyMsg The Mach message.
 154  */
 155 void gethostbyaddr_async_handleReply(void *replyMsg);
 156
 157 /*
 158  @typedef gethostbyname_async_callback
 159  @discussion Type of the callback function used when a
 160         gethostbyname_async_start() request is delivered.
 161  @param hent The resolved host entry.
 162  @param context The context provided when the request was initiated.
 163  */
 164 typedef void (*gethostbyname_async_callback)(struct hostent *hent, void *context);
 165
 166 /*!
 167  @function gethostbyname_async_start
 168  @description Asynchronously resolves a hostname
 169  @param name The hostname to be resolved.
 170  @param callout The function to be called when the specified
 171         hostname has been resolved.
 172  @param context A user specified context which will be passed
 173         to the callout function.
 174  @result A mach reply port which will be sent a message when
 175         the name resolution has completed. This message
 176         should be passed to the gethostbyname_async_handleReply
 177         function. A NULL value indicates that no hostname
 178         was specified or some other error occurred which
 179         prevented the resolution from being started.
 180  */
 181 mach_port_t gethostbyname_async_start(const char *name, gethostbyname_async_callback callout, void *context);
 182
 183 /*!
 184  @function gethostbyname_async_cancel
 185  @description Cancel an asynchronous request currently in progress.
 186  @param port The mach reply port associated with the request to be cancelled.
 187  */
 188 void gethostbyname_async_cancel(mach_port_t port);
 189
 190 /*!
 191  @function gethostbyname_async_handleReply
 192  @description This function should be called with the Mach message sent
 193         to the port returned by the call to gethostbyname_async_start.
 194         The reply message will be interpreted and will result in a
 195         call to the specified callout function.
 196  @param replyMsg The Mach message.
 197  */
 198 void gethostbyname_async_handleReply(void *replyMsg);
 199
 200 /*
 201  @typedef getipnodebyaddr_async_callback
 202  @discussion Type of the callback function used when a
 203         getipnodebyaddr_async_start() request is delivered.
 204  @param hent The resolved host entry. If not NULL, the caller
 205         must call freehostent() on the host entry.
 206  @param error If error code if the resolved host entry is NULL
 207  @param context The context provided when the request was initiated.
 208  */
 209 typedef void (*getipnodebyaddr_async_callback)(struct hostent *hent, int error, void *context);
 210
 211 /*!
 212  @function getipnodebyaddr_async_start
 213  @description Asynchronously resolves an Internet address
 214  @param addr The address to be resolved.
 215  @param len The length, in bytes, of the address.
 216  @param af The address family
 217  @param error
 218  @param callout The function to be called when the specified
 219         address has been resolved.
 220  @param context A user specified context which will be passed
 221         to the callout function.
 222  @result A mach reply port which will be sent a message when
 223         the addr resolution has completed. This message
 224         should be passed to the getipnodebyaddr_async_handleReply
 225         function. A NULL value indicates that no address
 226         was specified or some other error occurred which
 227         prevented the resolution from being started.
 228  */
 229 mach_port_t getipnodebyaddr_async_start(const void *addr, size_t len, int af, int *error, getipnodebyaddr_async_callback callout, void *context);
 230
 231 /*!
 232  @function getipnodebyaddr_async_cancel
 233  @description Cancel an asynchronous request currently in progress.
 234  @param port The mach reply port associated with the request to be cancelled.
 235  */
 236 void getipnodebyaddr_async_cancel(mach_port_t port);
 237
 238 /*!
 239  @function getipnodebyaddr_async_handleReply
 240  @description This function should be called with the Mach message sent
 241         to the port returned by the call to getipnodebyaddr_async_start.
 242         The reply message will be interpreted and will result in a
 243         call to the specified callout function.
 244  @param replyMsg The Mach message.
 245  */
 246 void getipnodebyaddr_async_handleReply(void *replyMsg);
 247
 248
 249 /*
 250  @typedef getipnodebyname_async_callback
 251  @discussion Type of the callback function used when a
 252         getipnodebyname_async_start() request is delivered.
 253  @param hent The resolved host entry. If not NULL, the caller
 254         must call freehostent() on the host entry.
 255  @param error If error code if the resolved host entry is NULL
 256  @param context The context provided when the request was initiated.
 257  */
 258 typedef void (*getipnodebyname_async_callback)(struct hostent *hent, int error, void *context);
 259
 260 /*!
 261  @function getipnodebyname_async_start
 262  @description Asynchronously resolves a hostname
 263  @param name The hostname to be resolved.
 264  @param af
 265  @param flags
 266  @param error
 267  @param callout The function to be called when the specified
 268         hostname has been resolved.
 269  @param context A user specified context which will be passed
 270         to the callout function.
 271  @result A mach reply port which will be sent a message when
 272         the name resolution has completed. This message
 273         should be passed to the getipnodebyname_async_handleReply
 274         function. A NULL value indicates that no hostname
 275         was specified or some other error occurred which
 276         prevented the resolution from being started.
 277  */
 278 mach_port_t getipnodebyname_async_start(const char *name, int af, int flags, int *error, getipnodebyname_async_callback callout, void *context);
 279
 280 /*!
 281  @function getipnodebyname_async_cancel
 282  @description Cancel an asynchronous request currently in progress.
 283  @param port The mach reply port associated with the request to be cancelled.
 284  */
 285 void getipnodebyname_async_cancel(mach_port_t port);
 286
 287 /*!
 288  @function getipnodebyname_async_handleReply
 289  @description This function should be called with the Mach message sent
 290         to the port returned by the call to getipnodebyname_async_start.
 291         The reply message will be interpreted and will result in a
 292         call to the specified callout function.
 293  @param replyMsg The Mach message.
 294  */
 295 void getipnodebyname_async_handleReply(void *replyMsg);
 296
 297 __END_DECLS
 298
 299 #endif /* !_NETDB_ASYNC_H_ */