/contrib/bind9/lib/dns/include/dns/lookup.h

https://bitbucket.org/freebsd/freebsd-head/ · C Header · 137 lines · 25 code · 13 blank · 99 comment · 0 complexity · d1ab33950c603795f3eab45e4d1c6ee3 MD5 · raw file

  1. /*
  2. * Copyright (C) 2004-2007, 2009 Internet Systems Consortium, Inc. ("ISC")
  3. * Copyright (C) 2000, 2001 Internet Software Consortium.
  4. *
  5. * Permission to use, copy, modify, and/or distribute this software for any
  6. * purpose with or without fee is hereby granted, provided that the above
  7. * copyright notice and this permission notice appear in all copies.
  8. *
  9. * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10. * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11. * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12. * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13. * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14. * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15. * PERFORMANCE OF THIS SOFTWARE.
  16. */
  17. /* $Id: lookup.h,v 1.14 2009/01/17 23:47:43 tbox Exp $ */
  18. #ifndef DNS_LOOKUP_H
  19. #define DNS_LOOKUP_H 1
  20. /*****
  21. ***** Module Info
  22. *****/
  23. /*! \file dns/lookup.h
  24. * \brief
  25. * The lookup module performs simple DNS lookups. It implements
  26. * the full resolver algorithm, both looking for local data and
  27. * resolving external names as necessary.
  28. *
  29. * MP:
  30. *\li The module ensures appropriate synchronization of data structures it
  31. * creates and manipulates.
  32. *
  33. * Reliability:
  34. *\li No anticipated impact.
  35. *
  36. * Resources:
  37. *\li TBS
  38. *
  39. * Security:
  40. *\li No anticipated impact.
  41. *
  42. * Standards:
  43. *\li RFCs: 1034, 1035, 2181, TBS
  44. *\li Drafts: TBS
  45. */
  46. #include <isc/lang.h>
  47. #include <isc/event.h>
  48. #include <dns/types.h>
  49. ISC_LANG_BEGINDECLS
  50. /*%
  51. * A 'dns_lookupevent_t' is returned when a lookup completes.
  52. * The sender field will be set to the lookup that completed. If 'result'
  53. * is ISC_R_SUCCESS, then 'names' will contain a list of names associated
  54. * with the address. The recipient of the event must not change the list
  55. * and must not refer to any of the name data after the event is freed.
  56. */
  57. typedef struct dns_lookupevent {
  58. ISC_EVENT_COMMON(struct dns_lookupevent);
  59. isc_result_t result;
  60. dns_name_t *name;
  61. dns_rdataset_t *rdataset;
  62. dns_rdataset_t *sigrdataset;
  63. dns_db_t *db;
  64. dns_dbnode_t *node;
  65. } dns_lookupevent_t;
  66. isc_result_t
  67. dns_lookup_create(isc_mem_t *mctx, dns_name_t *name, dns_rdatatype_t type,
  68. dns_view_t *view, unsigned int options, isc_task_t *task,
  69. isc_taskaction_t action, void *arg, dns_lookup_t **lookupp);
  70. /*%<
  71. * Finds the rrsets matching 'name' and 'type'.
  72. *
  73. * Requires:
  74. *
  75. *\li 'mctx' is a valid mctx.
  76. *
  77. *\li 'name' is a valid name.
  78. *
  79. *\li 'view' is a valid view which has a resolver.
  80. *
  81. *\li 'task' is a valid task.
  82. *
  83. *\li lookupp != NULL && *lookupp == NULL
  84. *
  85. * Returns:
  86. *
  87. *\li ISC_R_SUCCESS
  88. *\li ISC_R_NOMEMORY
  89. *
  90. *\li Any resolver-related error (e.g. ISC_R_SHUTTINGDOWN) may also be
  91. * returned.
  92. */
  93. void
  94. dns_lookup_cancel(dns_lookup_t *lookup);
  95. /*%<
  96. * Cancel 'lookup'.
  97. *
  98. * Notes:
  99. *
  100. *\li If 'lookup' has not completed, post its LOOKUPDONE event with a
  101. * result code of ISC_R_CANCELED.
  102. *
  103. * Requires:
  104. *
  105. *\li 'lookup' is a valid lookup.
  106. */
  107. void
  108. dns_lookup_destroy(dns_lookup_t **lookupp);
  109. /*%<
  110. * Destroy 'lookup'.
  111. *
  112. * Requires:
  113. *
  114. *\li '*lookupp' is a valid lookup.
  115. *
  116. *\li The caller has received the LOOKUPDONE event (either because the
  117. * lookup completed or because dns_lookup_cancel() was called).
  118. *
  119. * Ensures:
  120. *
  121. *\li *lookupp == NULL.
  122. */
  123. ISC_LANG_ENDDECLS
  124. #endif /* DNS_LOOKUP_H */