diff options
Diffstat (limited to 'mDNSResponder/mDNSMacOSX/DNSServiceDiscovery.h')
| -rw-r--r-- | mDNSResponder/mDNSMacOSX/DNSServiceDiscovery.h | 314 |
1 files changed, 314 insertions, 0 deletions
diff --git a/mDNSResponder/mDNSMacOSX/DNSServiceDiscovery.h b/mDNSResponder/mDNSMacOSX/DNSServiceDiscovery.h new file mode 100644 index 00000000..ae736477 --- /dev/null +++ b/mDNSResponder/mDNSMacOSX/DNSServiceDiscovery.h @@ -0,0 +1,314 @@ +/* -*- Mode: C; tab-width: 4 -*- + * + * Copyright (c) 2002 Apple Computer, Inc. All rights reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/*! @header DNS Service Discovery (Deprecated Mach-based API) + * + * @discussion This section describes the functions, callbacks, and data structures that + * make up the DNS Service Discovery API. + * + * The DNS Service Discovery API is part of Bonjour, Apple's implementation of + * zero-configuration networking (ZEROCONF). + * + * Bonjour allows you to register a network service, such as a + * printer or file server, so that it can be found by name or browsed + * for by service type and domain. Using Bonjour, applications can + * discover what services are available on the network, along with + * all necessary access information-such as name, IP address, and port + * number-for a given service. + * + * In effect, Bonjour combines the functions of a local DNS server + * and AppleTalk. Bonjour allows applications to provide user-friendly printer + * and server browsing, among other things, over standard IP networks. + * This behavior is a result of combining protocols such as multicast and DNS + * to add new functionality to the network (such as multicast DNS). + * + * Bonjour gives applications easy access to services over local IP + * networks without requiring the service or the application to support + * an AppleTalk or a Netbeui stack, and without requiring a DNS server + * for the local network. + * + * Note that this API was deprecated in Mac OS X 10.3, and replaced + * by the portable cross-platform /usr/include/dns_sd.h API. + */ + +#ifndef __DNS_SERVICE_DISCOVERY_H +#define __DNS_SERVICE_DISCOVERY_H + +#include <mach/mach_types.h> + +#include <sys/types.h> +#include <sys/socket.h> +#include <sys/cdefs.h> + +#include <netinet/in.h> + +#include <AvailabilityMacros.h> + +__BEGIN_DECLS + +/* Opaque internal data type */ +typedef struct _dns_service_discovery_t * dns_service_discovery_ref; + +/* possible reply flags values */ + +enum { + kDNSServiceDiscoveryNoFlags = 0, + kDNSServiceDiscoveryMoreRepliesImmediately = 1 << 0, +}; + + +/* possible error code values */ +typedef enum +{ + kDNSServiceDiscoveryWaiting = 1, + kDNSServiceDiscoveryNoError = 0, + // mDNS Error codes are in the range + // FFFE FF00 (-65792) to FFFE FFFF (-65537) + kDNSServiceDiscoveryUnknownErr = -65537, // 0xFFFE FFFF + kDNSServiceDiscoveryNoSuchNameErr = -65538, + kDNSServiceDiscoveryNoMemoryErr = -65539, + kDNSServiceDiscoveryBadParamErr = -65540, + kDNSServiceDiscoveryBadReferenceErr = -65541, + kDNSServiceDiscoveryBadStateErr = -65542, + kDNSServiceDiscoveryBadFlagsErr = -65543, + kDNSServiceDiscoveryUnsupportedErr = -65544, + kDNSServiceDiscoveryNotInitializedErr = -65545, + kDNSServiceDiscoveryNoCache = -65546, + kDNSServiceDiscoveryAlreadyRegistered = -65547, + kDNSServiceDiscoveryNameConflict = -65548, + kDNSServiceDiscoveryInvalid = -65549, + kDNSServiceDiscoveryMemFree = -65792 // 0xFFFE FF00 +} DNSServiceRegistrationReplyErrorType; + +typedef uint32_t DNSRecordReference; + + +/*! + @function DNSServiceResolver_handleReply + @discussion This function should be called with the Mach message sent + to the port returned by the call to DNSServiceResolverResolve. + The reply message will be interpreted and will result in a + call to the specified callout function. + @param replyMsg The Mach message. + */ +void DNSServiceDiscovery_handleReply(void *replyMsg); + +/* Service Registration */ + +typedef void (*DNSServiceRegistrationReply)( + DNSServiceRegistrationReplyErrorType errorCode, + void *context + ); + +/*! + @function DNSServiceRegistrationCreate + @discussion Register a named service with DNS Service Discovery + @param name The name of this service instance (e.g. "Steve's Printer") + @param regtype The service type (e.g. "_printer._tcp." -- see + RFC 2782 (DNS SRV) and <http://www.iana.org/assignments/port-numbers>) + @param domain The domain in which to register the service (e.g. "apple.com.") + @param port The local port on which this service is being offered (in network byte order) + @param txtRecord Optional protocol-specific additional information + @param callBack The DNSServiceRegistrationReply function to be called + @param context A user specified context which will be passed to the callout function. + @result A dns_registration_t + */ +dns_service_discovery_ref DNSServiceRegistrationCreate +( + const char *name, + const char *regtype, + const char *domain, + uint16_t port, + const char *txtRecord, + DNSServiceRegistrationReply callBack, + void *context +) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_3; + +/***************************************************************************/ +/* DNS Domain Enumeration */ + +typedef enum +{ + DNSServiceDomainEnumerationReplyAddDomain, // Domain found + DNSServiceDomainEnumerationReplyAddDomainDefault, // Domain found (and should be selected by default) + DNSServiceDomainEnumerationReplyRemoveDomain, // Domain has been removed from network +} DNSServiceDomainEnumerationReplyResultType; + +typedef enum +{ + DNSServiceDiscoverReplyFlagsFinished, + DNSServiceDiscoverReplyFlagsMoreComing, +} DNSServiceDiscoveryReplyFlags; + +typedef void (*DNSServiceDomainEnumerationReply)( + DNSServiceDomainEnumerationReplyResultType resultType, // One of DNSServiceDomainEnumerationReplyResultType + const char *replyDomain, + DNSServiceDiscoveryReplyFlags flags, // DNS Service Discovery reply flags information + void *context + ); + +/*! + @function DNSServiceDomainEnumerationCreate + @discussion Asynchronously create a DNS Domain Enumerator + @param registrationDomains A boolean indicating whether you are looking + for recommended registration domains + (e.g. equivalent to the AppleTalk zone list in the AppleTalk Control Panel) + or recommended browsing domains + (e.g. equivalent to the AppleTalk zone list in the Chooser). + @param callBack The function to be called when domains are found or removed + @param context A user specified context which will be passed to the callout function. + @result A dns_registration_t + */ +dns_service_discovery_ref DNSServiceDomainEnumerationCreate +( + int registrationDomains, + DNSServiceDomainEnumerationReply callBack, + void *context +) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_3; + +/***************************************************************************/ +/* DNS Service Browser */ + +typedef enum +{ + DNSServiceBrowserReplyAddInstance, // Instance of service found + DNSServiceBrowserReplyRemoveInstance // Instance has been removed from network +} DNSServiceBrowserReplyResultType; + +typedef void (*DNSServiceBrowserReply)( + DNSServiceBrowserReplyResultType resultType, // One of DNSServiceBrowserReplyResultType + const char *replyName, + const char *replyType, + const char *replyDomain, + DNSServiceDiscoveryReplyFlags flags, // DNS Service Discovery reply flags information + void *context + ); + +/*! + @function DNSServiceBrowserCreate + @discussion Asynchronously create a DNS Service browser + @param regtype The type of service + @param domain The domain in which to find the service + @param callBack The function to be called when service instances are found or removed + @param context A user specified context which will be passed to the callout function. + @result A dns_registration_t + */ +dns_service_discovery_ref DNSServiceBrowserCreate +( + const char *regtype, + const char *domain, + DNSServiceBrowserReply callBack, + void *context +) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_3; + +/***************************************************************************/ +/* Resolver requests */ + +typedef void (*DNSServiceResolverReply)( + struct sockaddr *interface, // Needed for scoped addresses like link-local + struct sockaddr *address, + const char *txtRecord, + DNSServiceDiscoveryReplyFlags flags, // DNS Service Discovery reply flags information + void *context + ); + +/*! + @function DNSServiceResolverResolve + @discussion Resolved a named instance of a service to its address, port, and + (optionally) other demultiplexing information contained in the TXT record. + @param name The name of the service instance + @param regtype The type of service + @param domain The domain in which to find the service + @param callBack The DNSServiceResolverReply function to be called when the specified + address has been resolved. + @param context A user specified context which will be passed to the callout function. + @result A dns_registration_t + */ + +dns_service_discovery_ref DNSServiceResolverResolve +( + const char *name, + const char *regtype, + const char *domain, + DNSServiceResolverReply callBack, + void *context +) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_3; + +/***************************************************************************/ +/* Mach port accessor and deallocation */ + +/*! + @function DNSServiceDiscoveryMachPort + @discussion Returns the mach port for a dns_service_discovery_ref + @param registration A dns_service_discovery_ref as returned from DNSServiceRegistrationCreate + @result A mach reply port which will be sent messages as appropriate. + These messages should be passed to the DNSServiceDiscovery_handleReply + function. A NULL value indicates that no address was + specified or some other error occurred which prevented the + resolution from being started. + */ +mach_port_t DNSServiceDiscoveryMachPort(dns_service_discovery_ref dnsServiceDiscovery) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_3; + +/*! + @function DNSServiceDiscoveryDeallocate + @discussion Deallocates the DNS Service Discovery type / closes the connection to the server + @param dnsServiceDiscovery A dns_service_discovery_ref as returned from a creation or enumeration call + @result void + */ +void DNSServiceDiscoveryDeallocate(dns_service_discovery_ref dnsServiceDiscovery) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_3; + +/***************************************************************************/ +/* Registration updating */ + + +/*! + @function DNSServiceRegistrationAddRecord + @discussion Request that the mDNS Responder add the DNS Record of a specific type + @param dnsServiceDiscovery A dns_service_discovery_ref as returned from a DNSServiceRegistrationCreate call + @param rrtype A standard DNS Resource Record Type, from http://www.iana.org/assignments/dns-parameters + @param rdlen Length of the data + @param rdata Opaque binary Resource Record data, up to 64 kB. + @param ttl time to live for the added record. + @result DNSRecordReference An opaque reference that can be passed to the update and remove record calls. If an error occurs, this value will be zero or negative + */ +DNSRecordReference DNSServiceRegistrationAddRecord(dns_service_discovery_ref dnsServiceDiscovery, uint16_t rrtype, uint16_t rdlen, const char *rdata, uint32_t ttl) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_3; + +/*! + @function DNSServiceRegistrationUpdateRecord + @discussion Request that the mDNS Responder add the DNS Record of a specific type + @param dnsServiceDiscovery A dns_service_discovery_ref as returned from a DNSServiceRegistrationCreate call + @param dnsRecordReference A dnsRecordReference as returned from a DNSServiceRegistrationAddRecord call + @param rdlen Length of the data + @param rdata Opaque binary Resource Record data, up to 64 kB. + @param ttl time to live for the updated record. + @result DNSServiceRegistrationReplyErrorType If an error occurs, this value will be non zero + */ +DNSServiceRegistrationReplyErrorType DNSServiceRegistrationUpdateRecord(dns_service_discovery_ref ref, DNSRecordReference reference, uint16_t rdlen, const char *rdata, uint32_t ttl) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_3; + +/*! + @function DNSServiceRegistrationRemoveRecord + @discussion Request that the mDNS Responder remove the DNS Record(s) of a specific type + @param dnsServiceDiscovery A dns_service_discovery_ref as returned from a DNSServiceRegistrationCreate call + @param dnsRecordReference A dnsRecordReference as returned from a DNSServiceRegistrationAddRecord call + @result DNSServiceRegistrationReplyErrorType If an error occurs, this value will be non zero + */ +DNSServiceRegistrationReplyErrorType DNSServiceRegistrationRemoveRecord(dns_service_discovery_ref ref, DNSRecordReference reference) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_3; + + +__END_DECLS + +#endif /* __DNS_SERVICE_DISCOVERY_H */ |