path: root/mDNSResponder/mDNSMacOSX/DNSServiceDiscovery.h

/* -*- 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 */