mDNSMacOSX/Private/dns_services.h

   1 /* -*- Mode: C; tab-width: 4 -*-
   2  *
   3  * Copyright (c) 2012-2018 Apple Inc. All rights reserved.
   4  *
   5  *
   6  * @header      Interface to DNSX SPI
   7  *
   8  * @discussion  Describes the functions and data structures
   9  *              that make up the DNSX SPI
  10  */
  11
  12 #ifndef _DNS_SERVICES_H
  13 #define _DNS_SERVICES_H
  14
  15 #include <dispatch/dispatch.h>
  16
  17 #if (defined(__GNUC__) && (__GNUC__ >= 4))
  18 #define DNS_SERVICES_EXPORT __attribute__((visibility("default")))
  19 #else
  20 #define DNS_SERVICES_EXPORT
  21 #endif
  22
  23 // DNSXConnRef: Opaque internal data type
  24 typedef struct _DNSXConnRef_t *DNSXConnRef;
  25
  26 typedef enum
  27 {
  28     kDNSX_NoError                   =  0,
  29     kDNSX_UnknownErr                = -65537,   /* 0xFFFE FFFF */
  30     kDNSX_NoMem                     = -65539,   /* No Memory   */
  31     kDNSX_BadParam                  = -65540,   /* Client passed invalid arg */
  32     kDNSX_Busy                      = -65551,   /* DNS Proxy already in use: incorrect use of SPI by client */
  33     kDNSX_DaemonNotRunning          = -65563    /* Daemon not running */
  34 } DNSXErrorType;
  35
  36 // A max of 5 input interfaces can be processed
  37 #define MaxInputIf 5
  38 #define IfIndex uint64_t
  39 #define kDNSIfindexAny 0
  40
  41 // Enable DNS Proxy with an appropriate parameter defined below
  42 typedef enum
  43 {
  44     kDNSProxyEnable = 1
  45     // Other values reserved for future use
  46 } DNSProxyParameters;
  47
  48 /*********************************************************************************************
  49  *
  50  *  Enable DNS Proxy Functionality
  51  *
  52  *********************************************************************************************/
  53
  54 /* DNSXEnableProxy : Turns ON the DNS Proxy (Details below)
  55  *
  56  * DNSXEnableProxyReply() parameters:
  57  *
  58  * connRef:                  The DNSXConnRef initialized by DNSXEnableProxy().
  59  *
  60  * errCode:                  Will be kDNSX_NoError on success, otherwise will indicate the
  61  *                           failure that occurred.
  62  *
  63  */
  64
  65 typedef void (*DNSXEnableProxyReply)
  66 (
  67     DNSXConnRef           connRef,
  68     DNSXErrorType         errCode
  69 );
  70
  71 /* DNSXEnableProxy
  72  *
  73  * Enables the DNS Proxy functionality which will remain ON until the client explicitly turns it OFF
  74  * by passing the returned DNSXConnRef to DNSXRefDeAlloc(), or the client exits or crashes.
  75  *
  76  * DNSXEnableProxy() Parameters:
  77  *
  78  * connRef:                   A pointer to DNSXConnRef that is initialized to NULL.
  79  *                            If the call succeeds it will be initialized to a non-NULL value.
  80  *                            Client terminates the DNS Proxy by passing this DNSXConnRef to DNSXRefDeAlloc().
  81  *
  82  * proxyparam:                Enable DNS Proxy functionality with parameters that are described in
  83  *                            DNSProxyParameters above.
  84  *
  85  * inIfindexArr[MaxInputIf]:  List of input interfaces from which the DNS queries will be accepted and
  86  *                            forwarded to the output interface specified below. The daemon processes
  87  *                            MaxInputIf entries in the list. For eg. if one has less than MaxInputIfs
  88  *                            values, just initialize the other values to be 0. Note: This field needs to
  89  *                            be initialized by the client.
  90  *
  91  * outIfindex:                Output interface on which the query will be forwarded.
  92  *                            Passing kDNSIfindexAny causes DNS Queries to be sent on the primary interface.
  93  *
  94  *                            Note: It is the responsibility of the client to ensure the input/output interface
  95  *                            indexes are valid.
  96  *
  97  * clientq:                   Queue the client wants to schedule the callBack on (Note: Must not be NULL)
  98  *
  99  * callBack:                  CallBack function for the client that indicates success or failure.
 100  *                            Note: callback may be invoked more than once, For e.g. if enabling DNS Proxy
 101  *                            first succeeds and the daemon possibly crashes sometime later.
 102  *
 103  * return value:              Returns kDNSX_NoError when no error otherwise returns an error code indicating
 104  *                            the error that occurred. Note: A return value of kDNSX_NoError does not mean
 105  *                            that DNS Proxy was successfully enabled. The callBack may asynchronously
 106  *                            return an error (such as kDNSX_DaemonNotRunning)
 107  *
 108  */
 109
 110 DNS_SERVICES_EXPORT
 111 DNSXErrorType DNSXEnableProxy
 112 (
 113     DNSXConnRef              *connRef,
 114     DNSProxyParameters       proxyparam,
 115     IfIndex                  inIfindexArr[MaxInputIf],
 116     IfIndex                  outIfindex,
 117     dispatch_queue_t         clientq,
 118     DNSXEnableProxyReply     callBack
 119  );
 120
 121 /* DNSXRefDeAlloc()
 122  *
 123  * Terminate a connection with the daemon and free memory associated with the DNSXConnRef.
 124  * Used to Disable DNS Proxy on that connection.
 125  *
 126  * connRef:        A DNSXConnRef initialized by any of the DNSX*() calls.
 127  *
 128  */
 129 DNS_SERVICES_EXPORT
 130 void DNSXRefDeAlloc(DNSXConnRef connRef);
 131
 132 #endif