1/* -*- Mode: C; tab-width: 4 -*- 2 * 3 * Copyright (c) 2012 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 18typedef struct _DNSXConnRef_t *DNSXConnRef; 19 20typedef enum 21{ 22 kDNSX_NoError = 0, 23 kDNSX_UnknownErr = -65537, /* 0xFFFE FFFF */ 24 kDNSX_NoMem = -65539, 25 kDNSX_BadParam = -65540, 26 kDNSX_DaemonNotRunning = -65563, /* Background daemon not running */ 27 kDNSX_DictError = -65565, /* Dictionary Error */ 28 kDNSX_Engaged = -65566, /* DNS Proxy is in use by another client */ 29 kDNSX_Timeout = -65568 30} DNSXErrorType; 31 32// A max of 5 input interfaces can be processed at one time 33#define MaxInputIf 5 34#define IfIndex uint64_t 35#define kDNSIfindexAny 0 36 37// Enable DNS Proxy with an appropriate parameter defined below 38typedef enum 39{ 40 kDNSProxyEnable = 1 41 // Other values reserved for future use 42} DNSProxyParameters; 43 44/********************************************************************************************* 45* 46* Enable DNS Proxy Functionality 47* 48*********************************************************************************************/ 49 50/* DNSXEnableProxy : Turns ON the DNS Proxy (Details below) 51 * 52 * DNSXEnableProxyReply() parameters: 53 * 54 * connRef: The DNSXConnRef initialized by DNSXEnableProxy(). 55 * 56 * errCode: Will be kDNSX_NoError on success, otherwise will indicate the 57 * failure that occurred. Other parameters are undefined if 58 * errCode is nonzero. 59 * 60 */ 61 62typedef void (*DNSXEnableProxyReply) 63( 64 DNSXConnRef connRef, 65 DNSXErrorType errCode 66); 67 68/* DNSXEnableProxy 69 * 70 * Enables the DNS Proxy functionality which will remain ON until the client terminates explictly (or exits/crashes). 71 * Client can turn it OFF by passing the returned DNSXConnRef to DNSXRefDeAlloc() 72 * 73 * DNSXEnableProxy() Parameters: 74 * 75 * connRef: A pointer to DNSXConnRef that is initialized to NULL when called for the first 76 * time. If the call succeeds it will be initialized to a non-NULL value. 77 * Client terminates the DNS Proxy by passing this DNSXConnRef to DNSXRefDeAlloc(). 78 * 79 * proxyparam: Enable DNS Proxy functionality with parameters that are described in 80 * DNSProxyParameters above. 81 * 82 * inIfindexArr[MaxInputIf]: List of input interfaces from which the DNS queries will be accepted and 83 * forwarded to the output interface specified below. The daemon processes 84 * MaxInputIf entries in the list. For eg. if one has less than MaxInputIfs 85 * values, just initialize the other values to be 0. Note: This field needs to 86 * be initialized by the client. 87 * 88 * outIfindex: Output interface on which the query will be forwarded. 89 * Passing kDNSIfindexAny causes DNS Queries to be sent on the primary interface. 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 eg. 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/ kDNSX_Engaged) 101 * 102 */ 103 104DNSXErrorType 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 */ 122void DNSXRefDeAlloc(DNSXConnRef connRef); 123 124#endif /* _DNS_SERVICES_H */ 125