diff options
Diffstat (limited to 'mDNSResponder/mDNSWindows/DLL.NET/dnssd_NET.h')
| -rwxr-xr-x | mDNSResponder/mDNSWindows/DLL.NET/dnssd_NET.h | 1392 |
1 files changed, 1392 insertions, 0 deletions
diff --git a/mDNSResponder/mDNSWindows/DLL.NET/dnssd_NET.h b/mDNSResponder/mDNSWindows/DLL.NET/dnssd_NET.h new file mode 100755 index 00000000..3e0196d2 --- /dev/null +++ b/mDNSResponder/mDNSWindows/DLL.NET/dnssd_NET.h @@ -0,0 +1,1392 @@ +/* -*- 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[] + ); + }; + } +} |