mDNSMacOSX/Private/dns_services.h

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