/* -*- Mode: C; tab-width: 4 -*-
*
* Copyright (c) 2003-2004 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.
*
* NOTE:
*
* These .Net APIs are a work in progress, currently being discussed and refined.
* If you plan to build an application based on these APIs, you may wish to
* statically link this code into your application, or otherwise distribute
* the DLL so that it installs into the same folder as your application
* (not into any common system area where it might interfere with other
* applications using a future completed version of these APIs).
* If you plan to do this, please be sure to inform us by sending email
* to bonjour@apple.com to let us know.
* You may want to discuss what you're doing on the Bonjour mailing
* list to see if others in similar positions have any suggestions for you:
*
* <http://lists.apple.com/bonjour-dev/>
*
*/
#pragma once
#include <dns_sd.h>
#include <vcclr.h>
#include <memory>
#include <winsock2.h>
using namespace System;
using namespace System::Net;
using namespace System::Runtime::InteropServices;
using namespace System::Threading;
using namespace System::Collections;
namespace Apple
{
namespace DNSSD
{
public __gc class ServiceRef;
public __value enum ServiceFlags : int
{
MoreComing = 1,
/* MoreComing indicates to a callback that at least one more result is
* queued and will be delivered following immediately after this one.
* Applications should not update their UI to display browse
* results when the MoreComing flag is set, because this would
* result in a great deal of ugly flickering on the screen.
* Applications should instead wait until until MoreComing is not set,
* and then update their UI.
* When MoreComing is not set, that doesn't mean there will be no more
* answers EVER, just that there are no more answers immediately
* available right now at this instant. If more answers become available
* in the future they will be delivered as usual.
*/
Add = 2,
Default = 4,
/* Flags for domain enumeration and browse/query reply callbacks.
* "Default" applies only to enumeration and is only valid in
* conjuction with "Add". An enumeration callback with the "Add"
* flag NOT set indicates a "Remove", i.e. the domain is no longer
* valid.
*/
NoAutoRename = 8,
/* Flag for specifying renaming behavior on name conflict when registering
* non-shared records. By default, name conflicts are automatically handled
* by renaming the service. NoAutoRename overrides this behavior - with this
* flag set, name conflicts will result in a callback. The NoAutorename flag
* is only valid if a name is explicitly specified when registering a service
* (i.e. the default name is not used.)
*/
Shared = 16,
Unique = 32,
/* Flag for registering individual records on a connected
* DNSServiceRef. Shared indicates that there may be multiple records
* with this name on the network (e.g. PTR records). Unique indicates that
the
* record's name is to be unique on the network (e.g. SRV records).
*/
BrowseDomains = 64,
RegistrationDomains = 128,
/* Flags for specifying domain enumeration type in DNSServiceEnumerateDomain
s.
* BrowseDomains enumerates domains recommended for browsing, RegistrationDo
mains
* enumerates domains recommended for registration.
*/
};
public __value enum ErrorCode : int
{
NoError = 0,
Unknown = -65537,
NoSuchName = -65538,
NoMemory = -65539,
BadParam = -65540,
BadReference = -65541,
BadState = -65542,
BadFlags = -65543,
Unsupported = -65544,
AlreadyRegistered = -65547,
NameConflict = -65548,
Invalid = -65549,
Incompatible = -65551,
BadinterfaceIndex = -65552
/*
* mDNS Error codes are in the range
* FFFE FF00 (-65792) to FFFE FFFF (-65537)
*/
};
public __gc class DNSServiceException
:
public Exception
{
public:
DNSServiceException
(
int err
);
DNSServiceException
(
String * message,
System::Exception * innerException
);
int err;
};
/*
* class RecordRef
*
* This is a thin MC++ class facade on top of a DNSRecordRef
*/
public __gc class RecordRef
{
public:
RecordRef()
{
m_impl = new RecordRefImpl;
m_impl->m_ref = NULL;
}
~RecordRef()
{
delete m_impl;
}
__nogc class RecordRefImpl
{
public:
DNSRecordRef m_ref;
};
RecordRefImpl * m_impl;
};
/*
* class ServiceRef
*
* This is a thin MC++ class facade on top of a DNSServiceRef
*/
public __gc class ServiceRef : public IDisposable
{
public:
ServiceRef(Object * callback);
~ServiceRef();
/*
* This does an underlying DNSServiceRefDeallocate(). After
* calling Dispose, the ServiceRef is no longer usable.
*/
void
Dispose();
/*
* Internal - Dispatch an EnumerateDomains callback
*/
void
EnumerateDomainsDispatch
(
ServiceFlags flags,
int interfaceIndex,
ErrorCode errorCode,
String * replyDomain
);
/*
* Internal - Dispatch a Register callback
*/
void
RegisterDispatch
(
ServiceFlags flags,
ErrorCode errorCode,
String * name,
String * regtype,
String * domain
);
/*
* Internal - Dispatch a Browse callback
*/
void
BrowseDispatch
(
ServiceFlags flags,
int interfaceIndex,
ErrorCode errorCode,
String * serviceName,
String * regtype,
String * replyDomain
);
/*
* Internal - Dispatch a Resolve callback
*/
void
ResolveDispatch
(
ServiceFlags flags,
int interfaceIndex,
ErrorCode errorCode,
String * fullname,
String * hosttarget,
int port,
Byte txtRecord[]
);
/*
* Internal - Dispatch a RegisterRecord callback
*/
void
RegisterRecordDispatch
(
ServiceFlags flags,
ErrorCode errorCode,
RecordRef * record
);
/*
* Internal - Dispatch a QueryRecord callback
*/
void
QueryRecordDispatch
(
ServiceFlags flags,
int interfaceIndex,
ErrorCode errorCode,
String * fullname,
int rrtype,
int rrclass,
Byte rdata[],
int ttl
);
/*
* Internal - A non managed class to wrap a DNSServiceRef
*/
__nogc class ServiceRefImpl
{
public:
ServiceRefImpl
(
ServiceRef * outer
);
~ServiceRefImpl();
/*
* Sets up events for threaded operation
*/
void
SetupEvents();
/*
* Main processing thread
*/
void
ProcessingThread();
/*
* Calls DNSServiceRefDeallocate()
*/
void
Dispose();
/*
* Called from dnssd.dll
*/
static void DNSSD_API
EnumerateDomainsCallback
(
DNSServiceRef sdRef,
DNSServiceFlags flags,
uint32_t interfaceIndex,
DNSServiceErrorType errorCode,
const char * replyDomain,
void * context
);
static void DNSSD_API
RegisterCallback
(
DNSServiceRef ref,
DNSServiceFlags flags,
DNSServiceErrorType errorCode,
const char * name,
const char * regtype,
const char * domain,
void * context
);
static void DNSSD_API
BrowseCallback
(
DNSServiceRef sdRef,
DNSServiceFlags flags,
uint32_t interfaceIndex,
DNSServiceErrorType errorCode,
const char * serviceName,
const char * regtype,
const char * replyDomain,
void * context
);
static void DNSSD_API
ResolveCallback
(
DNSServiceRef sdRef,
DNSServiceFlags flags,
uint32_t interfaceIndex,
DNSServiceErrorType errorCode,
const char * fullname,
const char * hosttarget,
uint16_t notAnIntPort,
uint16_t txtLen,
const char * txtRecord,
void * context
);
static void DNSSD_API
RegisterRecordCallback
(
DNSServiceRef sdRef,
DNSRecordRef RecordRef,
DNSServiceFlags flags,
DNSServiceErrorType errorCode,
void * context
);
static void DNSSD_API
QueryRecordCallback
(
DNSServiceRef DNSServiceRef,
DNSServiceFlags flags,
uint32_t interfaceIndex,
DNSServiceErrorType errorCode,
const char * fullname,
uint16_t rrtype,
uint16_t rrclass,
uint16_t rdlen,
const void * rdata,
uint32_t ttl,
void * context
);
SOCKET m_socket;
HANDLE m_socketEvent;
HANDLE m_stopEvent;
DWORD m_threadId;
bool m_disposed;
DNSServiceRef m_ref;
gcroot<ServiceRef*> m_outer;
};
void
StartThread();
void
ProcessingThread();
bool m_bDisposed;
Object * m_callback;
Thread * m_thread;
ServiceRefImpl * m_impl;
};
/*********************************************************************************************
*
* TXT Record Construction Functions
*
*********************************************************************************************/
/*
* A typical calling sequence for TXT record construction is something like:
*
* DNSService.TextRecord tr = new DNSService.TextRecord(1024);
* tr.SetValue();
* tr.SetValue();
* tr.SetValue();
* ...
* DNSServiceRegister( ... tr.GetLength(), tr.GetBytes() ... );
*/
/* TextRecord
*
* Opaque internal data type.
* Note: Represents a DNS-SD TXT record.
*/
/* TextRecord::TextRecord()
*
* Creates a new empty TextRecord .
*
*/
public __gc class TextRecord
{
public:
TextRecord()
{
m_impl = new TextRecordImpl();
TXTRecordCreate(&m_impl->m_ref, 0, NULL);
}
~TextRecord()
{
TXTRecordDeallocate(&m_impl->m_ref);
delete m_impl;
}
__nogc class TextRecordImpl
{
public:
TXTRecordRef m_ref;
};
TextRecordImpl * m_impl;
/* SetValue()
*
* Adds a key (optionally with value) to a TextRecord. If the "key" already
* exists in the TextRecord, then the current value will be replaced with
* the new value.
* Keys may exist in four states with respect to a given TXT record:
* - Absent (key does not appear at all)
* - Present with no value ("key" appears alone)
* - Present with empty value ("key=" appears in TXT record)
* - Present with non-empty value ("key=value" appears in TXT record)
* For more details refer to "Data Syntax for DNS-SD TXT Records" in
* <http://files.dns-sd.org/draft-cheshire-dnsext-dns-sd.txt>
*
* key: A null-terminated string which only contains printable ASCII
* values (0x20-0x7E), excluding '=' (0x3D). Keys should be
* 14 characters or less (not counting the terminating null).
*
* value: Any binary value. For values that represent
* textual data, UTF-8 is STRONGLY recommended.
* For values that represent textual data, valueSize
* should NOT include the terminating null (if any)
* at the end of the string.
* If NULL, then "key" will be added with no value.
* If non-NULL but valueSize is zero, then "key=" will be
* added with empty value.
*
* exceptions: Throws kDNSServiceErr_Invalid if the "key" string contains
* illegal characters.
* Throws kDNSServiceErr_NoMemory if adding this key would
* exceed the available storage.
*/
void
SetValue
(
String * key,
Byte value[] /* may be NULL */
);
/* RemoveValue()
*
* Removes a key from a TextRecord. The "key" must be an
* ASCII string which exists in the TextRecord.
*
* key: A key name which exists in the TextRecord.
*
* exceptions: Throws kDNSServiceErr_NoSuchKey if the "key" does not
* exist in the TextRecord.
*
*/
void
RemoveValue
(
String * key
);
/* GetLength()
*
* Allows you to determine the length of the raw bytes within a TextRecord.
*
* return value : Returns the size of the raw bytes inside a TextRecord
* which you can pass directly to DNSServiceRegister() or
* to DNSServiceUpdateRecord().
* Returns 0 if the TextRecord is empty.
*
*/
int
GetLength
(
);
/* GetBytes()
*
* Allows you to retrieve a pointer to the raw bytes within a TextRecord.
*
* return value: Returns a pointer to the bytes inside the TextRecord
* which you can pass directly to DNSServiceRegister() or
* to DNSServiceUpdateRecord().
*
*/
Byte
GetBytes
(
) __gc[];
/*********************************************************************************************
*
* TXT Record Parsing Functions
*
*********************************************************************************************/
/*
* A typical calling sequence for TXT record parsing is something like:
*
* Receive TXT record data in DNSServiceResolve() callback
* if (TXTRecordContainsKey(txtLen, txtRecord, "key")) then do something
* val1ptr = DNSService.TextService.GetValue(txtRecord, "key1", &len1);
* val2ptr = DNSService.TextService.GetValue(txtRecord, "key2", &len2);
* ...
* return;
*
*/
/* ContainsKey()
*
* Allows you to determine if a given TXT Record contains a specified key.
*
* txtRecord: Pointer to the received TXT Record bytes.
*
* key: A null-terminated ASCII string containing the key name.
*
* return value: Returns 1 if the TXT Record contains the specified key.
* Otherwise, it returns 0.
*
*/
static public bool
ContainsKey
(
Byte txtRecord[],
String * key
);
/* GetValueBytes()
*
* Allows you to retrieve the value for a given key from a TXT Record.
*
* txtRecord: Pointer to the received TXT Record bytes.
*
* key: A null-terminated ASCII string containing the key name.
*
* return value: Returns NULL if the key does not exist in this TXT record,
* or exists with no value (to differentiate between
* these two cases use ContainsKey()).
* Returns byte array
* if the key exists with empty or non-empty value.
* For empty value, length of byte array will be zero.
* For non-empty value, it will be the length of value data.
*/
static public Byte
GetValueBytes
(
Byte txtRecord[],
String * key
) __gc[];
/* GetCount()
*
* Returns the number of keys stored in the TXT Record. The count
* can be used with TXTRecordGetItemAtIndex() to iterate through the keys.
*
* txtRecord: Pointer to the received TXT Record bytes.
*
* return value: Returns the total number of keys in the TXT Record.
*
*/
static public int
GetCount
(
Byte txtRecord[]
);
/* GetItemAtIndex()
*
* Allows you to retrieve a key name and value pointer, given an index into
* a TXT Record. Legal index values range from zero to TXTRecordGetCount()-1.
* It's also possible to iterate through keys in a TXT record by simply
* calling TXTRecordGetItemAtIndex() repeatedly, beginning with index zero
* and increasing until TXTRecordGetItemAtIndex() returns kDNSServiceErr_Invalid.
*
* On return:
* For keys with no value, *value is set to NULL and *valueLen is zero.
* For keys with empty value, *value is non-NULL and *valueLen is zero.
* For keys with non-empty value, *value is non-NULL and *valueLen is non-zero.
*
* txtRecord: Pointer to the received TXT Record bytes.
*
* index: An index into the TXT Record.
*
* key: A string buffer used to store the key name.
* On return, the buffer contains a string
* giving the key name. DNS-SD TXT keys are usually
* 14 characters or less.
*
* return value: Record bytes that holds the value data.
*
* exceptions: Throws kDNSServiceErr_Invalid if index is greater than
* GetCount()-1.
*/
static public Byte
GetItemAtIndex
(
Byte txtRecord[],
int index,
[Out] String ** key
) __gc[];
};
public __abstract __gc class DNSService
{
public:
/*********************************************************************************************
*
* Domain Enumeration
*
*********************************************************************************************/
/* DNSServiceEnumerateDomains()
*
* Asynchronously enumerate domains available for browsing and registration.
* Currently, the only domain returned is "local.", but other domains will be returned in future.
*
* The enumeration MUST be cancelled via DNSServiceRefDeallocate() when no more domains
* are to be found.
*
*
* EnumerateDomainsReply Delegate
*
* This Delegate is invoked upon a reply from an EnumerateDomains call.
*
* sdRef: The DNSServiceRef initialized by DNSServiceEnumerateDomains().
*
* flags: Possible values are:
* MoreComing
* Add
* Default
*
* interfaceIndex: Specifies the interface on which the domain exists. (The index for a given
* interface is determined via the if_nametoindex() family of calls.)
*
* errorCode: Will be NoError (0) on success, otherwise indicates
* the failure that occurred (other parameters are undefined if errorCode is nonzero).
*
* replyDomain: The name of the domain.
*
*/
__delegate void
EnumerateDomainsReply
(
ServiceRef * sdRef,
ServiceFlags flags,
int interfaceIndex,
ErrorCode errorCode,
String * replyDomain
);
/* DNSServiceEnumerateDomains() Parameters:
*
*
* flags: Possible values are:
* BrowseDomains to enumerate domains recommended for browsing.
* RegistrationDomains to enumerate domains recommended
* for registration.
*
* interfaceIndex: If non-zero, specifies the interface on which to look for domains.
* (the index for a given interface is determined via the if_nametoindex()
* family of calls.) Most applications will pass 0 to enumerate domains on
* all interfaces.
*
* callback: The delegate to be called when a domain is found or the call asynchronously
* fails.
*
*
* return value: Returns initialize ServiceRef on succeses (any subsequent, asynchronous
* errors are delivered to the delegate), otherwise throws an exception indicating
* the error that occurred (the callback is not invoked and the ServiceRef
* is not initialized.)
*/
static public ServiceRef*
EnumerateDomains
(
int flags,
int interfaceIndex,
EnumerateDomainsReply * callback
);
/*********************************************************************************************
*
* Service Registration
*
*********************************************************************************************/
/* Register a service that is discovered via Browse() and Resolve() calls.
*
* RegisterReply() Callback Parameters:
*
* sdRef: The ServiceRef initialized by Register().
*
* flags: Currently unused, reserved for future use.
*
* errorCode: Will be NoError on success, otherwise will
* indicate the failure that occurred (including name conflicts, if the
* NoAutoRename flag was passed to the
* callout.) Other parameters are undefined if errorCode is nonzero.
*
* name: The service name registered (if the application did not specify a name in
* DNSServiceRegister(), this indicates what name was automatically chosen).
*
* regtype: The type of service registered, as it was passed to the callout.
*
* domain: The domain on which the service was registered (if the application did not
* specify a domain in Register(), this indicates the default domain
* on which the service was registered).
*
*/
__delegate void
RegisterReply
(
ServiceRef * sdRef,
ServiceFlags flags,
ErrorCode errorCode,
String * name,
String * regtype,
String * domain
);
/* Register() Parameters:
*
* flags: Indicates the renaming behavior on name conflict (most applications
* will pass 0). See flag definitions above for details.
*
* interfaceIndex: If non-zero, specifies the interface on which to register the service
* (the index for a given interface is determined via the if_nametoindex()
* family of calls.) Most applications will pass 0 to register on all
* available interfaces. Pass -1 to register a service only on the local
* machine (service will not be visible to remote hosts.)
*
* name: If non-NULL, specifies the service name to be registered.
* Most applications will not specify a name, in which case the
* computer name is used (this name is communicated to the client via
* the callback).
*
* regtype: The service type followed by the protocol, separated by a dot
* (e.g. "_ftp._tcp"). The transport protocol must be "_tcp" or "_udp".
* New service types should be registered at htp://www.dns-sd.org/ServiceTypes.html.
*
* domain: If non-NULL, specifies the domain on which to advertise the service.
* Most applications will not specify a domain, instead automatically
* registering in the default domain(s).
*
* host: If non-NULL, specifies the SRV target host name. Most applications
* will not specify a host, instead automatically using the machine's
* default host name(s). Note that specifying a non-NULL host does NOT
* create an address record for that host - the application is responsible
* for ensuring that the appropriate address record exists, or creating it
* via DNSServiceRegisterRecord().
*
* port: The port, in host byte order, on which the service accepts connections.
* Pass 0 for a "placeholder" service (i.e. a service that will not be discovered
* by browsing, but will cause a name conflict if another client tries to
* register that same name). Most clients will not use placeholder services.
*
* txtRecord: The txt record rdata. May be NULL. Note that a non-NULL txtRecord
* MUST be a properly formatted DNS TXT record, i.e. <length byte> <data>
* <length byte> <data> ...
*
* callback: The delegate to be called when the registration completes or asynchronously
* fails. The client MAY pass NULL for the callback - The client will NOT be notified
* of the default values picked on its behalf, and the client will NOT be notified of any
* asynchronous errors (e.g. out of memory errors, etc.) that may prevent the registration
* of the service. The client may NOT pass the NoAutoRename flag if the callback is NULL.
* The client may still deregister the service at any time via DNSServiceRefDeallocate().
*
* return value: Returns initialize ServiceRef (any subsequent, asynchronous
* errors are delivered to the callback), otherwise throws an exception indicating
* the error that occurred (the callback is never invoked and the DNSServiceRef
* is not initialized.)
*
*/
static public ServiceRef*
Register
(
int flags,
int interfaceIndex,
String * name,
String * regtype,
String * domain,
String * host,
int port,
Byte txtRecord[],
RegisterReply * callback
);
/* AddRecord()
*
* Add a record to a registered service. The name of the record will be the same as the
* registered service's name.
* The record can later be updated or deregistered by passing the RecordRef initialized
* by this function to UpdateRecord() or RemoveRecord().
*
*
* Parameters;
*
* sdRef: A ServiceRef initialized by Register().
*
* RecordRef: A pointer to an uninitialized RecordRef. Upon succesfull completion of this
* call, this ref may be passed to UpdateRecord() or RemoveRecord().
* If the above ServiceRef is disposed, RecordRef is also
* invalidated and may not be used further.
*
* flags: Currently ignored, reserved for future use.
*
* rrtype: The type of the record (e.g. TXT, SRV, etc), as defined in nameser.h.
*
* rdata: The raw rdata to be contained in the added resource record.
*
* ttl: The time to live of the resource record, in seconds.
*
* return value: Returns initialized RecordRef, otherwise throws
* an exception indicating the error that occurred (the RecordRef is not initialized).
*/
static public RecordRef*
AddRecord
(
ServiceRef * sref,
int flags,
int rrtype,
Byte rdata[],
int ttl
);
/* UpdateRecord
*
* Update a registered resource record. The record must either be:
* - The primary txt record of a service registered via Register()
* - A record added to a registered service via AddRecord()
* - An individual record registered by RegisterRecord()
*
*
* Parameters:
*
* sdRef: A ServiceRef that was initialized by Register()
* or CreateConnection().
*
* RecordRef: A RecordRef initialized by AddRecord, or NULL to update the
* service's primary txt record.
*
* flags: Currently ignored, reserved for future use.
*
* rdata: The new rdata to be contained in the updated resource record.
*
* ttl: The time to live of the updated resource record, in seconds.
*
* return value: No return value on success, otherwise throws an exception
* indicating the error that occurred.
*/
static public void
UpdateRecord
(
ServiceRef * sref,
RecordRef * record,
int flags,
Byte rdata[],
int ttl
);
/* RemoveRecord
*
* Remove a record previously added to a service record set via AddRecord(), or deregister
* an record registered individually via RegisterRecord().
*
* Parameters:
*
* sdRef: A ServiceRef initialized by Register() (if the
* record being removed was registered via AddRecord()) or by
* CreateConnection() (if the record being removed was registered via
* RegisterRecord()).
*
* recordRef: A RecordRef initialized by a successful call to AddRecord()
* or RegisterRecord().
*
* flags: Currently ignored, reserved for future use.
*
* return value: Nothing on success, otherwise throws an
* exception indicating the error that occurred.
*/
static public void
RemoveRecord
(
ServiceRef * sref,
RecordRef * record,
int flags
);
/*********************************************************************************************
*
* Service Discovery
*
*********************************************************************************************/
/* Browse for instances of a service.
*
*
* BrowseReply() Parameters:
*
* sdRef: The DNSServiceRef initialized by Browse().
*
* flags: Possible values are MoreComing and Add.
* See flag definitions for details.
*
* interfaceIndex: The interface on which the service is advertised. This index should
* be passed to Resolve() when resolving the service.
*
* errorCode: Will be NoError (0) on success, otherwise will
* indicate the failure that occurred. Other parameters are undefined if
* the errorCode is nonzero.
*
* serviceName: The service name discovered.
*
* regtype: The service type, as passed in to Browse().
*
* domain: The domain on which the service was discovered (if the application did not
* specify a domain in Browse(), this indicates the domain on which the
* service was discovered.)
*
*/
__delegate void
BrowseReply
(
ServiceRef * sdRef,
ServiceFlags flags,
int interfaceIndex,
ErrorCode errorCode,
String * name,
String * type,
String * domain
);
/* DNSServiceBrowse() Parameters:
*
* sdRef: A pointer to an uninitialized ServiceRef. Call ServiceRef.Dispose()
* to terminate the browse.
*
* flags: Currently ignored, reserved for future use.
*
* interfaceIndex: If non-zero, specifies the interface on which to browse for services
* (the index for a given interface is determined via the if_nametoindex()
* family of calls.) Most applications will pass 0 to browse on all available
* interfaces. Pass -1 to only browse for services provided on the local host.
*
* regtype: The service type being browsed for followed by the protocol, separated by a
* dot (e.g. "_ftp._tcp"). The transport protocol must be "_tcp" or "_udp".
*
* domain: If non-NULL, specifies the domain on which to browse for services.
* Most applications will not specify a domain, instead browsing on the
* default domain(s).
*
* callback: The delegate to be called when an instance of the service being browsed for
* is found, or if the call asynchronously fails.
*
* return value: Returns initialized ServiceRef on succeses (any subsequent, asynchronous
* errors are delivered to the callback), otherwise throws an exception indicating
* the error that occurred (the callback is not invoked and the ServiceRef
* is not initialized.)
*/
static public ServiceRef*
Browse
(
int flags,
int interfaceIndex,
String * regtype,
String * domain,
BrowseReply * callback
);
/* ResolveReply() Parameters:
*
* Resolve a service name discovered via Browse() to a target host name, port number, and
* txt record.
*
* Note: Applications should NOT use Resolve() solely for txt record monitoring - use
* QueryRecord() instead, as it is more efficient for this task.
*
* Note: When the desired results have been returned, the client MUST terminate the resolve by calling
* ServiceRef.Dispose().
*
* Note: Resolve() behaves correctly for typical services that have a single SRV record and
* a single TXT record (the TXT record may be empty.) To resolve non-standard services with multiple
* SRV or TXT records, QueryRecord() should be used.
*
* ResolveReply Callback Parameters:
*
* sdRef: The DNSServiceRef initialized by Resolve().
*
* flags: Currently unused, reserved for future use.
*
* interfaceIndex: The interface on which the service was resolved.
*
* errorCode: Will be NoError (0) on success, otherwise will
* indicate the failure that occurred. Other parameters are undefined if
* the errorCode is nonzero.
*
* fullname: The full service domain name, in the form <servicename>.<protocol>.<domain>.
* (Any literal dots (".") are escaped with a backslash ("\."), and literal
* backslashes are escaped with a second backslash ("\\"), e.g. a web server
* named "Dr. Pepper" would have the fullname "Dr\.\032Pepper._http._tcp.local.").
* This is the appropriate format to pass to standard system DNS APIs such as
* res_query(), or to the special-purpose functions included in this API that
* take fullname parameters.
*
* hosttarget: The target hostname of the machine providing the service. This name can
* be passed to functions like gethostbyname() to identify the host's IP address.
*
* port: The port, in host byte order, on which connections are accepted for this service.
*
* txtRecord: The service's primary txt record, in standard txt record format.
*
*/
__delegate void
ResolveReply
(
ServiceRef * sdRef,
ServiceFlags flags,
int interfaceIndex,
ErrorCode errorCode,
String * fullName,
String * hostName,
int port,
Byte txtRecord[]
);
/* Resolve() Parameters
*
* flags: Currently ignored, reserved for future use.
*
* interfaceIndex: The interface on which to resolve the service. The client should
* pass the interface on which the servicename was discovered, i.e.
* the interfaceIndex passed to the DNSServiceBrowseReply callback,
* or 0 to resolve the named service on all available interfaces.
*
* name: The servicename to be resolved.
*
* regtype: The service type being resolved followed by the protocol, separated by a
* dot (e.g. "_ftp._tcp"). The transport protocol must be "_tcp" or "_udp".
*
* domain: The domain on which the service is registered, i.e. the domain passed
* to the DNSServiceBrowseReply callback.
*
* callback: The delegate to be called when a result is found, or if the call
* asynchronously fails.
*
*
* return value: Returns initialized ServiceRef on succeses (any subsequent, asynchronous
* errors are delivered to the callback), otherwise throws an exception indicating
* the error that occurred (the callback is never invoked and the DNSServiceRef
* is not initialized.)
*/
static public ServiceRef*
Resolve
(
int flags,
int interfaceIndex,
String * name,
String * regtype,
String * domain,
ResolveReply * callback
);
/*********************************************************************************************
*
* Special Purpose Calls (most applications will not use these)
*
*********************************************************************************************/
/* CreateConnection/RegisterRecord
*
* Register an individual resource record on a connected ServiceRef.
*
* Note that name conflicts occurring for records registered via this call must be handled
* by the client in the callback.
*
*
* RecordReply() parameters:
*
* sdRef: The connected ServiceRef initialized by
* CreateConnection().
*
* RecordRef: The RecordRef initialized by RegisterRecord(). If the above
* ServiceRef.Dispose is called, this RecordRef is
* invalidated, and may not be used further.
*
* flags: Currently unused, reserved for future use.
*
* errorCode: Will be NoError on success, otherwise will
* indicate the failure that occurred (including name conflicts.)
* Other parameters are undefined if errorCode is nonzero.
*
*/
__delegate void
RegisterRecordReply
(
ServiceRef * sdRef,
ServiceFlags flags,
ErrorCode errorCode,
RecordRef * record
);
/* CreateConnection()
*
* Create a connection to the daemon allowing efficient registration of
* multiple individual records.
*
*
* Parameters:
*
* callback: The delegate to be called when a result is found, or if the call
* asynchronously fails (e.g. because of a name conflict.)
*
* return value: Returns initialize ServiceRef on success, otherwise throws
* an exception indicating the specific failure that occurred (in which
* case the ServiceRef is not initialized).
*/
static public ServiceRef*
CreateConnection
(
RegisterRecordReply * callback
);
/* RegisterRecord() Parameters:
*
* sdRef: A ServiceRef initialized by CreateConnection().
*
* RecordRef: A pointer to an uninitialized RecordRef. Upon succesfull completion of this
* call, this ref may be passed to UpdateRecord() or RemoveRecord().
* (To deregister ALL records registered on a single connected ServiceRef
* and deallocate each of their corresponding RecordRefs, call
* ServiceRef.Dispose()).
*
* flags: Possible values are Shared or Unique
* (see flag type definitions for details).
*
* interfaceIndex: If non-zero, specifies the interface on which to register the record
* (the index for a given interface is determined via the if_nametoindex()
* family of calls.) Passing 0 causes the record to be registered on all interfaces.
* Passing -1 causes the record to only be visible on the local host.
*
* fullname: The full domain name of the resource record.
*
* rrtype: The numerical type of the resource record (e.g. PTR, SRV, etc), as defined
* in nameser.h.
*
* rrclass: The class of the resource record, as defined in nameser.h (usually 1 for the
* Internet class).
*
* rdata: A pointer to the raw rdata, as it is to appear in the DNS record.
*
* ttl: The time to live of the resource record, in seconds.
*
*
* return value: Returns initialize RecordRef on succeses (any subsequent, asynchronous
* errors are delivered to the callback), otherwise throws an exception indicating
* the error that occurred (the callback is never invoked and the RecordRef is
* not initialized.)
*/
static public RecordRef*
RegisterRecord
(
ServiceRef * sdRef,
ServiceFlags flags,
int interfaceIndex,
String * fullname,
int rrtype,
int rrclass,
Byte rdata[],
int ttl
);
/* DNSServiceQueryRecord
*
* Query for an arbitrary DNS record.
*
*
* QueryRecordReply() Delegate Parameters:
*
* sdRef: The ServiceRef initialized by QueryRecord().
*
* flags: Possible values are MoreComing and
* Add. The Add flag is NOT set for PTR records
* with a ttl of 0, i.e. "Remove" events.
*
* interfaceIndex: The interface on which the query was resolved (the index for a given
* interface is determined via the if_nametoindex() family of calls).
*
* errorCode: Will be kDNSServiceErr_NoError on success, otherwise will
* indicate the failure that occurred. Other parameters are undefined if
* errorCode is nonzero.
*
* fullname: The resource record's full domain name.
*
* rrtype: The resource record's type (e.g. PTR, SRV, etc) as defined in nameser.h.
*
* rrclass: The class of the resource record, as defined in nameser.h (usually 1).
*
* rdata: The raw rdata of the resource record.
*
* ttl: The resource record's time to live, in seconds.
*
*/
__delegate void
QueryRecordReply
(
ServiceRef * sdRef,
ServiceFlags flags,
int interfaceIndex,
ErrorCode errorCode,
String * fullName,
int rrtype,
int rrclass,
Byte rdata[],
int ttl
);
/* QueryRecord() Parameters:
*
* flags: Pass LongLivedQuery to create a "long-lived" unicast
* query in a non-local domain. Without setting this flag, unicast queries
* will be one-shot - that is, only answers available at the time of the call
* will be returned. By setting this flag, answers (including Add and Remove
* events) that become available after the initial call is made will generate
* callbacks. This flag has no effect on link-local multicast queries.
*
* interfaceIndex: If non-zero, specifies the interface on which to issue the query
* (the index for a given interface is determined via the if_nametoindex()
* family of calls.) Passing 0 causes the name to be queried for on all
* interfaces. Passing -1 causes the name to be queried for only on the
* local host.
*
* fullname: The full domain name of the resource record to be queried for.
*
* rrtype: The numerical type of the resource record to be queried for (e.g. PTR, SRV, etc)
* as defined in nameser.h.
*
* rrclass: The class of the resource record, as defined in nameser.h
* (usually 1 for the Internet class).
*
* callback: The delegate to be called when a result is found, or if the call
* asynchronously fails.
*
*
* return value: Returns initialized ServiceRef on succeses (any subsequent, asynchronous
* errors are delivered to the callback), otherwise throws an exception indicating
* the error that occurred (the callback is never invoked and the ServiceRef
* is not initialized.)
*/
static public ServiceRef*
QueryRecord
(
ServiceFlags flags,
int interfaceIndex,
String * fullname,
int rrtype,
int rrclass,
QueryRecordReply * callback
);
/* ReconfirmRecord
*
* Instruct the daemon to verify the validity of a resource record that appears to
* be out of date (e.g. because tcp connection to a service's target failed.)
* Causes the record to be flushed from the daemon's cache (as well as all other
* daemons' caches on the network) if the record is determined to be invalid.
*
* Parameters:
*
* flags: Currently unused, reserved for future use.
*
* fullname: The resource record's full domain name.
*
* rrtype: The resource record's type (e.g. PTR, SRV, etc) as defined in nameser.h.
*
* rrclass: The class of the resource record, as defined in nameser.h (usually 1).
*
* rdata: The raw rdata of the resource record.
*
*/
static public void
ReconfirmRecord
(
ServiceFlags flags,
int interfaceIndex,
String * fullname,
int rrtype,
int rrclass,
Byte rdata[]
);
};
}
}